<div dir="ltr">Sorry for being afk for so long.<div><br></div><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
I'm dropping the old syntax documentation as it has the problem of being<br>quickly outdated by changes and largely unnecessary to people not involved<br>in creating the language, but using it, which is the whole point of the<br>
documentation.</blockquote><div><br></div><div>The "old syntax documentation" is actually the most modern piece of the TableGen documentation before you made this change, and I think you misunderstood the purpose of the LangRef document, as this commit sort of defeats the point of the LangRef document.</div>
<div><br></div><div><span style="font-size:13px;font-family:arial,sans-serif">The reason I named it LangRef is precisely to avoid "the problem of being quickly outdated by changes". We have a culture of keeping docs/LangRef up to date for all IR changes. TableGen/LangRef is meant to serve the same purpose for TableGen.</span></div>
<div><div><br></div><div>TableGen/LangRef is supposed to be a reference spec (that could be used for an alternative implementation), not a "introduction/overview". The reason I originally wrote TableGen/LangRef is so that we could start giving TableGen a proper language definition (not just "read the source") in doing so pave the way for cleaning up the implementation. TableGen/LangRef is very much (maybe only) intended for people "<span style="font-family:arial,sans-serif;font-size:13px">involved </span><span style="font-family:arial,sans-serif;font-size:13px">in creating the language". It serves as a nexus for where to document *new* changes (although there is sort of a moratorium on changing the TableGen language) and in doing so prevents silent, uncontrolled growth of the language.</span></div>
<div><br></div><div><div>I would recommend restoring the original contents of TableGen/LangRef and moving its current contents to a "LangOverview" or "LangIntro" or something like that.</div></div><div>
<br></div><div>-- Sean Silva</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Mar 20, 2014 at 12:08 PM, Renato Golin <span dir="ltr"><<a href="mailto:renato.golin@linaro.org" target="_blank">renato.golin@linaro.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Author: rengolin<br>
Date: Thu Mar 20 11:08:34 2014<br>
New Revision: 204351<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=204351&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=204351&view=rev</a><br>
Log:<br>
Re-factor TableGen docs<br>
<br>
This is mainly a movement of content around to give place to new content<br>
allowing different people to add bits to it in the right place. There is some<br>
new content, but mostly to fill the gaps left by text movement.<br>
<br>
I'm dropping the old syntax documentation as it has the problem of being<br>
quickly outdated by changes and largely unnecessary to people not involved<br>
in creating the language, but using it, which is the whole point of the<br>
documentation.<br>
<br>
Added:<br>
llvm/trunk/docs/TableGen/BackEnds.rst<br>
llvm/trunk/docs/TableGen/Deficiencies.rst<br>
llvm/trunk/docs/TableGen/index.rst<br>
Modified:<br>
llvm/trunk/docs/TableGen/LangRef.rst<br>
llvm/trunk/docs/index.rst<br>
<br>
Added: llvm/trunk/docs/TableGen/BackEnds.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/BackEnds.rst?rev=204351&view=auto" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/BackEnds.rst?rev=204351&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/TableGen/BackEnds.rst (added)<br>
+++ llvm/trunk/docs/TableGen/BackEnds.rst Thu Mar 20 11:08:34 2014<br>
@@ -0,0 +1,281 @@<br>
+=================<br>
+TableGen BackEnds<br>
+=================<br>
+<br>
+.. contents::<br>
+ :local:<br>
+<br>
+Introduction<br>
+============<br>
+<br>
+TableGen backends are at the core of TableGen's functionality. The source files<br>
+provide the semantics to a generated (in memory) structure, but it's up to the<br>
+backend to print this out in a way that is meaningful to the user (normally a<br>
+C program including a file or a textual list of warnings, options and error<br>
+messages).<br>
+<br>
+TableGen is used by both LLVM and Clang with very different goals. LLVM uses it<br>
+as a way to automate the generation of massive amounts of information regarding<br>
+instructions, schedules, cores and architecture features. Some backends generate<br>
+output that is consumed by more than one source file, so they need to be created<br>
+in a way that is easy to use pre-processor tricks. Some backends can also print<br>
+C code structures, so that they can be directly included as-is.<br>
+<br>
+Clang, on the other hand, uses it mainly for diagnostic messages (errors,<br>
+warnings, tips) and attributes, so more on the textual end of the scale.<br>
+<br>
+LLVM BackEnds<br>
+=============<br>
+<br>
+.. warning::<br>
+ This document is raw. Each section below needs three sub-sections: description<br>
+ of its purpose with a list of users, output generated from generic input, and<br>
+ finally why it needed a new backend (in case there's something similar).<br>
+<br>
+Emitter<br>
+-------<br>
+<br>
+Generate machine code emitter.<br>
+<br>
+RegisterInfo<br>
+------------<br>
+<br>
+Generate registers and register classes info.<br>
+<br>
+InstrInfo<br>
+---------<br>
+<br>
+Generate instruction descriptions.<br>
+<br>
+AsmWriter<br>
+---------<br>
+<br>
+Generate calling convention descriptions.<br>
+<br>
+AsmMatcher<br>
+----------<br>
+<br>
+Generate assembly writer.<br>
+<br>
+Disassembler<br>
+------------<br>
+<br>
+Generate disassembler.<br>
+<br>
+PseudoLowering<br>
+--------------<br>
+<br>
+Generate pseudo instruction lowering.<br>
+<br>
+CallingConv<br>
+-----------<br>
+<br>
+Generate assembly instruction matcher.<br>
+<br>
+DAGISel<br>
+-------<br>
+<br>
+Generate a DAG instruction selector.<br>
+<br>
+DFAPacketizer<br>
+-------------<br>
+<br>
+Generate DFA Packetizer for VLIW targets.<br>
+<br>
+FastISel<br>
+--------<br>
+<br>
+Generate a "fast" instruction selector.<br>
+<br>
+Subtarget<br>
+---------<br>
+<br>
+Generate subtarget enumerations.<br>
+<br>
+Intrinsic<br>
+---------<br>
+<br>
+Generate intrinsic information.<br>
+<br>
+TgtIntrinsic<br>
+------------<br>
+<br>
+Generate target intrinsic information.<br>
+<br>
+OptParserDefs<br>
+-------------<br>
+<br>
+Print enum values for a class.<br>
+<br>
+CTags<br>
+-----<br>
+<br>
+Generate ctags-compatible index.<br>
+<br>
+<br>
+Clang BackEnds<br>
+==============<br>
+<br>
+ClangAttrClasses<br>
+----------------<br>
+<br>
+Generate clang attribute clases.<br>
+<br>
+ClangAttrParserStringSwitches<br>
+-----------------------------<br>
+<br>
+Generate all parser-related attribute string switches.<br>
+<br>
+ClangAttrImpl<br>
+-------------<br>
+<br>
+Generate clang attribute implementations.<br>
+<br>
+ClangAttrList<br>
+-------------<br>
+<br>
+Generate a clang attribute list.<br>
+<br>
+ClangAttrPCHRead<br>
+----------------<br>
+<br>
+Generate clang PCH attribute reader.<br>
+<br>
+ClangAttrPCHWrite<br>
+-----------------<br>
+<br>
+Generate clang PCH attribute writer.<br>
+<br>
+ClangAttrSpellingList<br>
+---------------------<br>
+<br>
+Generate a clang attribute spelling list.<br>
+<br>
+ClangAttrSpellingListIndex<br>
+--------------------------<br>
+<br>
+Generate a clang attribute spelling index.<br>
+<br>
+ClangAttrASTVisitor<br>
+-------------------<br>
+<br>
+Generate a recursive AST visitor for clang attribute.<br>
+<br>
+ClangAttrTemplateInstantiate<br>
+----------------------------<br>
+<br>
+Generate a clang template instantiate code.<br>
+<br>
+ClangAttrParsedAttrList<br>
+-----------------------<br>
+<br>
+Generate a clang parsed attribute list.<br>
+<br>
+ClangAttrParsedAttrImpl<br>
+-----------------------<br>
+<br>
+Generate the clang parsed attribute helpers.<br>
+<br>
+ClangAttrParsedAttrKinds<br>
+------------------------<br>
+<br>
+Generate a clang parsed attribute kinds.<br>
+<br>
+ClangAttrDump<br>
+-------------<br>
+<br>
+Generate clang attribute dumper.<br>
+<br>
+ClangDiagsDefs<br>
+--------------<br>
+<br>
+Generate Clang diagnostics definitions.<br>
+<br>
+ClangDiagGroups<br>
+---------------<br>
+<br>
+Generate Clang diagnostic groups.<br>
+<br>
+ClangDiagsIndexName<br>
+-------------------<br>
+<br>
+Generate Clang diagnostic name index.<br>
+<br>
+ClangCommentNodes<br>
+-----------------<br>
+<br>
+Generate Clang AST comment nodes.<br>
+<br>
+ClangDeclNodes<br>
+--------------<br>
+<br>
+Generate Clang AST declaration nodes.<br>
+<br>
+ClangStmtNodes<br>
+--------------<br>
+<br>
+Generate Clang AST statement nodes.<br>
+<br>
+ClangSACheckers<br>
+---------------<br>
+<br>
+Generate Clang Static Analyzer checkers.<br>
+<br>
+ClangCommentHTMLTags<br>
+--------------------<br>
+<br>
+Generate efficient matchers for HTML tag names that are used in documentation comments.<br>
+<br>
+ClangCommentHTMLTagsProperties<br>
+------------------------------<br>
+<br>
+Generate efficient matchers for HTML tag properties.<br>
+<br>
+ClangCommentHTMLNamedCharacterReferences<br>
+----------------------------------------<br>
+<br>
+Generate function to translate named character references to UTF-8 sequences.<br>
+<br>
+ClangCommentCommandInfo<br>
+-----------------------<br>
+<br>
+Generate command properties for commands that are used in documentation comments.<br>
+<br>
+ClangCommentCommandList<br>
+-----------------------<br>
+<br>
+Generate list of commands that are used in documentation comments.<br>
+<br>
+ArmNeon<br>
+-------<br>
+<br>
+Generate arm_neon.h for clang.<br>
+<br>
+ArmNeonSema<br>
+-----------<br>
+<br>
+Generate ARM NEON sema support for clang.<br>
+<br>
+ArmNeonTest<br>
+-----------<br>
+<br>
+Generate ARM NEON tests for clang.<br>
+<br>
+AttrDocs<br>
+--------<br>
+<br>
+Generate attribute documentation.<br>
+<br>
+How to write a back-end<br>
+=======================<br>
+<br>
+TODO.<br>
+<br>
+Until we get a step-by-step HowTo for writing TableGen backends, you can at<br>
+least grab the boilerplate (build system, new files, etc.) from Clang's<br>
+r173931.<br>
+<br>
+TODO: How they work, how to write one. This section should not contain details<br>
+about any particular backend, except maybe ``-print-enums`` as an example. This<br>
+should highlight the APIs in ``TableGen/Record.h``.<br>
+<br>
<br>
Added: llvm/trunk/docs/TableGen/Deficiencies.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/Deficiencies.rst?rev=204351&view=auto" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/Deficiencies.rst?rev=204351&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/TableGen/Deficiencies.rst (added)<br>
+++ llvm/trunk/docs/TableGen/Deficiencies.rst Thu Mar 20 11:08:34 2014<br>
@@ -0,0 +1,31 @@<br>
+=====================<br>
+TableGen Deficiencies<br>
+=====================<br>
+<br>
+.. contents::<br>
+ :local:<br>
+<br>
+Introduction<br>
+============<br>
+<br>
+Despite being very generic, TableGen has some deficiencies that have been<br>
+pointed out numerous times. The common theme is that, while TableGen allows<br>
+you to build Domain-Specific-Languages, the final languages that you create<br>
+lack the power of other DSLs, which in turn increase considerably the size<br>
+and complexity of TableGen files.<br>
+<br>
+At the same time, TableGen allows you to create virtually any meaning of<br>
+the basic concepts via custom-made back-ends, which can pervert the original<br>
+design and make it very hard for newcomers to understand it.<br>
+<br>
+There are some in favour of extending the semantics even more, but making sure<br>
+back-ends adhere to strict rules. Others suggesting we should move to more<br>
+powerful DSLs designed with specific purposes, or even re-using existing<br>
+DSLs.<br>
+<br>
+Known Problems<br>
+==============<br>
+<br>
+TODO: Add here frequently asked questions about why TableGen doesn't do<br>
+what you want, how it might, and how we could extend/restrict it to<br>
+be more use friendly.<br>
<br>
Modified: llvm/trunk/docs/TableGen/LangRef.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/LangRef.rst?rev=204351&r1=204350&r2=204351&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/LangRef.rst?rev=204351&r1=204350&r2=204351&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/TableGen/LangRef.rst (original)<br>
+++ llvm/trunk/docs/TableGen/LangRef.rst Thu Mar 20 11:08:34 2014<br>
@@ -2,8 +2,6 @@<br>
TableGen Language Reference<br>
===========================<br>
<br>
-.. sectionauthor:: Sean Silva <<a href="mailto:silvas@purdue.edu">silvas@purdue.edu</a>><br>
-<br>
.. contents::<br>
:local:<br>
<br>
@@ -18,369 +16,587 @@ This document is meant to be a normative<br>
in and of itself (i.e. how to understand a given construct in terms of how<br>
it affects the final set of records represented by the TableGen file). If<br>
you are unsure if this document is really what you are looking for, please<br>
-read :doc:`/TableGenFundamentals` first.<br>
-<br>
-Notation<br>
-========<br>
-<br>
-The lexical and syntax notation used here is intended to imitate<br>
-`Python's`_. In particular, for lexical definitions, the productions<br>
-operate at the character level and there is no implied whitespace between<br>
-elements. The syntax definitions operate at the token level, so there is<br>
-implied whitespace between tokens.<br>
-<br>
-.. _`Python's`: <a href="http://docs.python.org/py3k/reference/introduction.html#notation" target="_blank">http://docs.python.org/py3k/reference/introduction.html#notation</a><br>
-<br>
-Lexical Analysis<br>
-================<br>
-<br>
-TableGen supports BCPL (``// ...``) and nestable C-style (``/* ... */``)<br>
-comments.<br>
-<br>
-The following is a listing of the basic punctuation tokens::<br>
-<br>
- - + [ ] { } ( ) < > : ; . = ? #<br>
-<br>
-Numeric literals take one of the following forms:<br>
-<br>
-.. TableGen actually will lex some pretty strange sequences an interpret<br>
- them as numbers. What is shown here is an attempt to approximate what it<br>
- "should" accept.<br>
-<br>
-.. productionlist::<br>
- TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`<br>
- DecimalInteger: ["+" | "-"] ("0"..."9")+<br>
- HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+<br>
- BinInteger: "0b" ("0" | "1")+<br>
-<br>
-One aspect to note is that the :token:`DecimalInteger` token *includes* the<br>
-``+`` or ``-``, as opposed to having ``+`` and ``-`` be unary operators as<br>
-most languages do.<br>
-<br>
-TableGen has identifier-like tokens:<br>
-<br>
-.. productionlist::<br>
- ualpha: "a"..."z" | "A"..."Z" | "_"<br>
- TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*<br>
- TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*<br>
-<br>
-Note that unlike most languages, TableGen allows :token:`TokIdentifier` to<br>
-begin with a number. In case of ambiguity, a token will be interpreted as a<br>
-numeric literal rather than an identifier.<br>
-<br>
-TableGen also has two string-like literals:<br>
-<br>
-.. productionlist::<br>
- TokString: '"' <non-'"' characters and C-like escapes> '"'<br>
- TokCodeFragment: "[{" <shortest text not containing "}]"> "}]"<br>
-<br>
-:token:`TokCodeFragment` is essentially a multiline string literal<br>
-delimited by ``[{`` and ``}]``.<br>
-<br>
-.. note::<br>
- The current implementation accepts the following C-like escapes::<br>
-<br>
- \\ \' \" \t \n<br>
-<br>
-TableGen also has the following keywords::<br>
-<br>
- bit bits class code dag<br>
- def foreach defm field in<br>
- int let list multiclass string<br>
-<br>
-TableGen also has "bang operators" which have a<br>
-wide variety of meanings:<br>
-<br>
-.. productionlist::<br>
- BangOperator: one of<br>
- :!eq !if !head !tail !con<br>
- :!add !shl !sra !srl<br>
- :!cast !empty !subst !foreach !strconcat<br>
-<br>
-Syntax<br>
-======<br>
-<br>
-TableGen has an ``include`` mechanism. It does not play a role in the<br>
-syntax per se, since it is lexically replaced with the contents of the<br>
-included file.<br>
-<br>
-.. productionlist::<br>
- IncludeDirective: "include" `TokString`<br>
-<br>
-TableGen's top-level production consists of "objects".<br>
-<br>
-.. productionlist::<br>
- TableGenFile: `Object`*<br>
- Object: `Class` | `Def` | `Defm` | `Let` | `MultiClass` | `Foreach`<br>
-<br>
-``class``\es<br>
-------------<br>
-<br>
-.. productionlist::<br>
- Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`<br>
-<br>
-A ``class`` declaration creates a record which other records can inherit<br>
-from. A class can be parametrized by a list of "template arguments", whose<br>
-values can be used in the class body.<br>
-<br>
-A given class can only be defined once. A ``class`` declaration is<br>
-considered to define the class if any of the following is true:<br>
-<br>
-.. break ObjectBody into its consituents so that they are present here?<br>
-<br>
-#. The :token:`TemplateArgList` is present.<br>
-#. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.<br>
-#. The :token:`BaseClassList` in the :token:`ObjectBody` is present.<br>
-<br>
-You can declare an empty class by giving and empty :token:`TemplateArgList`<br>
-and an empty :token:`ObjectBody`. This can serve as a restricted form of<br>
-forward declaration: note that records deriving from the forward-declared<br>
-class will inherit no fields from it since the record expansion is done<br>
-when the record is parsed.<br>
-<br>
-.. productionlist::<br>
- TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"<br>
-<br>
-Declarations<br>
-------------<br>
-<br>
-.. Omitting mention of arcane "field" prefix to discourage its use.<br>
-<br>
-The declaration syntax is pretty much what you would expect as a C++<br>
-programmer.<br>
-<br>
-.. productionlist::<br>
- Declaration: `Type` `TokIdentifier` ["=" `Value`]<br>
-<br>
-It assigns the value to the identifer.<br>
-<br>
-Types<br>
------<br>
-<br>
-.. productionlist::<br>
- Type: "string" | "code" | "bit" | "int" | "dag"<br>
- :| "bits" "<" `TokInteger` ">"<br>
- :| "list" "<" `Type` ">"<br>
- :| `ClassID`<br>
- ClassID: `TokIdentifier`<br>
-<br>
-Both ``string`` and ``code`` correspond to the string type; the difference<br>
-is purely to indicate programmer intention.<br>
-<br>
-The :token:`ClassID` must identify a class that has been previously<br>
-declared or defined.<br>
-<br>
-Values<br>
-------<br>
-<br>
-.. productionlist::<br>
- Value: `SimpleValue` `ValueSuffix`*<br>
- ValueSuffix: "{" `RangeList` "}"<br>
- :| "[" `RangeList` "]"<br>
- :| "." `TokIdentifier`<br>
- RangeList: `RangePiece` ("," `RangePiece`)*<br>
- RangePiece: `TokInteger`<br>
- :| `TokInteger` "-" `TokInteger`<br>
- :| `TokInteger` `TokInteger`<br>
-<br>
-The peculiar last form of :token:`RangePiece` is due to the fact that the<br>
-"``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as<br>
-two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,<br>
-instead of "1", "-", and "5".<br>
-The :token:`RangeList` can be thought of as specifying "list slice" in some<br>
-contexts.<br>
-<br>
+read :doc:`the introduction <index>` first.<br>
<br>
-:token:`SimpleValue` has a number of forms:<br>
+TableGen syntax<br>
+===============<br>
<br>
+TableGen doesn't care about the meaning of data (that is up to the backend to<br>
+define), but it does care about syntax, and it enforces a simple type system.<br>
+This section describes the syntax and the constructs allowed in a TableGen file.<br>
+<br>
+TableGen primitives<br>
+-------------------<br>
+<br>
+TableGen comments<br>
+^^^^^^^^^^^^^^^^^<br>
+<br>
+TableGen supports C++ style "``//``" comments, which run to the end of the<br>
+line, and it also supports **nestable** "``/* */``" comments.<br>
+<br>
+.. _TableGen type:<br>
+<br>
+The TableGen type system<br>
+^^^^^^^^^^^^^^^^^^^^^^^^<br>
+<br>
+TableGen files are strongly typed, in a simple (but complete) type-system.<br>
+These types are used to perform automatic conversions, check for errors, and to<br>
+help interface designers constrain the input that they allow. Every `value<br>
+definition`_ is required to have an associated type.<br>
+<br>
+TableGen supports a mixture of very low-level types (such as ``bit``) and very<br>
+high-level types (such as ``dag``). This flexibility is what allows it to<br>
+describe a wide range of information conveniently and compactly. The TableGen<br>
+types are:<br>
+<br>
+``bit``<br>
+ A 'bit' is a boolean value that can hold either 0 or 1.<br>
+<br>
+``int``<br>
+ The 'int' type represents a simple 32-bit integer value, such as 5.<br>
+<br>
+``string``<br>
+ The 'string' type represents an ordered sequence of characters of arbitrary<br>
+ length.<br>
+<br>
+``bits<n>``<br>
+ A 'bits' type is an arbitrary, but fixed, size integer that is broken up<br>
+ into individual bits. This type is useful because it can handle some bits<br>
+ being defined while others are undefined.<br>
+<br>
+``list<ty>``<br>
+ This type represents a list whose elements are some other type. The<br>
+ contained type is arbitrary: it can even be another list type.<br>
+<br>
+Class type<br>
+ Specifying a class name in a type context means that the defined value must<br>
+ be a subclass of the specified class. This is useful in conjunction with<br>
+ the ``list`` type, for example, to constrain the elements of the list to a<br>
+ common base class (e.g., a ``list<Register>`` can only contain definitions<br>
+ derived from the "``Register``" class).<br>
+<br>
+``dag``<br>
+ This type represents a nestable directed graph of elements.<br>
+<br>
+To date, these types have been sufficient for describing things that TableGen<br>
+has been used for, but it is straight-forward to extend this list if needed.<br>
+<br>
+.. _TableGen expressions:<br>
+<br>
+TableGen values and expressions<br>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^<br>
+<br>
+TableGen allows for a pretty reasonable number of different expression forms<br>
+when building up values. These forms allow the TableGen file to be written in a<br>
+natural syntax and flavor for the application. The current expression forms<br>
+supported include:<br>
+<br>
+``?``<br>
+ uninitialized field<br>
+<br>
+``0b1001011``<br>
+ binary integer value<br>
+<br>
+``07654321``<br>
+ octal integer value (indicated by a leading 0)<br>
+<br>
+``7``<br>
+ decimal integer value<br>
+<br>
+``0x7F``<br>
+ hexadecimal integer value<br>
+<br>
+``"foo"``<br>
+ string value<br>
+<br>
+``[{ ... }]``<br>
+ usually called a "code fragment", but is just a multiline string literal<br>
+<br>
+``[ X, Y, Z ]<type>``<br>
+ list value. <type> is the type of the list element and is usually optional.<br>
+ In rare cases, TableGen is unable to deduce the element type in which case<br>
+ the user must specify it explicitly.<br>
+<br>
+``{ a, b, c }``<br>
+ initializer for a "bits<3>" value<br>
+<br>
+``value``<br>
+ value reference<br>
+<br>
+``value{17}``<br>
+ access to one bit of a value<br>
+<br>
+``value{15-17}``<br>
+ access to multiple bits of a value<br>
+<br>
+``DEF``<br>
+ reference to a record definition<br>
+<br>
+``CLASS<val list>``<br>
+ reference to a new anonymous definition of CLASS with the specified template<br>
+ arguments.<br>
+<br>
+``X.Y``<br>
+ reference to the subfield of a value<br>
+<br>
+``list[4-7,17,2-3]``<br>
+ A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.<br>
+ Elements may be included multiple times.<br>
+<br>
+``foreach <var> = [ <list> ] in { <body> }``<br>
+<br>
+``foreach <var> = [ <list> ] in <def>``<br>
+ Replicate <body> or <def>, replacing instances of <var> with each value<br>
+ in <list>. <var> is scoped at the level of the ``foreach`` loop and must<br>
+ not conflict with any other object introduced in <body> or <def>. Currently<br>
+ only ``def``\s are expanded within <body>.<br>
+<br>
+``foreach <var> = 0-15 in ...``<br>
+<br>
+``foreach <var> = {0-15,32-47} in ...``<br>
+ Loop over ranges of integers. The braces are required for multiple ranges.<br>
+<br>
+``(DEF a, b)``<br>
+ a dag value. The first element is required to be a record definition, the<br>
+ remaining elements in the list may be arbitrary other values, including<br>
+ nested ```dag``' values.<br>
+<br>
+``!strconcat(a, b)``<br>
+ A string value that is the result of concatenating the 'a' and 'b' strings.<br>
+<br>
+``str1#str2``<br>
+ "#" (paste) is a shorthand for !strconcat. It may concatenate things that<br>
+ are not quoted strings, in which case an implicit !cast<string> is done on<br>
+ the operand of the paste.<br>
+<br>
+``!cast<type>(a)``<br>
+ A symbol of type *type* obtained by looking up the string 'a' in the symbol<br>
+ table. If the type of 'a' does not match *type*, TableGen aborts with an<br>
+ error. !cast<string> is a special case in that the argument must be an<br>
+ object defined by a 'def' construct.<br>
+<br>
+``!subst(a, b, c)``<br>
+ If 'a' and 'b' are of string type or are symbol references, substitute 'b'<br>
+ for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.<br>
+<br>
+``!foreach(a, b, c)``<br>
+ For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy<br>
+ variable that should be declared as a member variable of an instantiated<br>
+ class. This operation is analogous to $(foreach) in GNU make.<br>
+<br>
+``!head(a)``<br>
+ The first element of list 'a.'<br>
+<br>
+``!tail(a)``<br>
+ The 2nd-N elements of list 'a.'<br>
+<br>
+``!empty(a)``<br>
+ An integer {0,1} indicating whether list 'a' is empty.<br>
+<br>
+``!if(a,b,c)``<br>
+ 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.<br>
+<br>
+``!eq(a,b)``<br>
+ 'bit 1' if string a is equal to string b, 0 otherwise. This only operates<br>
+ on string, int and bit objects. Use !cast<string> to compare other types of<br>
+ objects.<br>
+<br>
+Note that all of the values have rules specifying how they convert to values<br>
+for different types. These rules allow you to assign a value like "``7``"<br>
+to a "``bits<4>``" value, for example.<br>
+<br>
+Classes and definitions<br>
+-----------------------<br>
+<br>
+As mentioned in the :doc:`introduction <index>`, classes and definitions (collectively known as<br>
+'records') in TableGen are the main high-level unit of information that TableGen<br>
+collects. Records are defined with a ``def`` or ``class`` keyword, the record<br>
+name, and an optional list of "`template arguments`_". If the record has<br>
+superclasses, they are specified as a comma separated list that starts with a<br>
+colon character ("``:``"). If `value definitions`_ or `let expressions`_ are<br>
+needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,<br>
+the record ends with a semicolon.<br>
+<br>
+Here is a simple TableGen file:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class C { bit V = 1; }<br>
+ def X : C;<br>
+ def Y : C {<br>
+ string Greeting = "hello";<br>
+ }<br>
+<br>
+This example defines two definitions, ``X`` and ``Y``, both of which derive from<br>
+the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``<br>
+definition also gets the Greeting member as well.<br>
+<br>
+In general, classes are useful for collecting together the commonality between a<br>
+group of records and isolating it in a single place. Also, classes permit the<br>
+specification of default values for their subclasses, allowing the subclasses to<br>
+override them as they wish.<br>
+<br>
+.. _value definition:<br>
+.. _value definitions:<br>
+<br>
+Value definitions<br>
+^^^^^^^^^^^^^^^^^<br>
+<br>
+Value definitions define named entries in records. A value must be defined<br>
+before it can be referred to as the operand for another value definition or<br>
+before the value is reset with a `let expression`_. A value is defined by<br>
+specifying a `TableGen type`_ and a name. If an initial value is available, it<br>
+may be specified after the type with an equal sign. Value definitions require<br>
+terminating semicolons.<br>
+<br>
+.. _let expression:<br>
+.. _let expressions:<br>
+.. _"let" expressions within a record:<br>
+<br>
+'let' expressions<br>
+^^^^^^^^^^^^^^^^^<br>
+<br>
+A record-level let expression is used to change the value of a value definition<br>
+in a record. This is primarily useful when a superclass defines a value that a<br>
+derived class or definition wants to override. Let expressions consist of the<br>
+'``let``' keyword followed by a value name, an equal sign ("``=``"), and a new<br>
+value. For example, a new class could be added to the example above, redefining<br>
+the ``V`` field for all of its subclasses:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class D : C { let V = 0; }<br>
+ def Z : D;<br>
+<br>
+In this case, the ``Z`` definition will have a zero value for its ``V`` value,<br>
+despite the fact that it derives (indirectly) from the ``C`` class, because the<br>
+``D`` class overrode its value.<br>
+<br>
+.. _template arguments:<br>
+<br>
+Class template arguments<br>
+^^^^^^^^^^^^^^^^^^^^^^^^<br>
+<br>
+TableGen permits the definition of parameterized classes as well as normal<br>
+concrete classes. Parameterized TableGen classes specify a list of variable<br>
+bindings (which may optionally have defaults) that are bound when used. Here is<br>
+a simple example:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class FPFormat<bits<3> val> {<br>
+ bits<3> Value = val;<br>
+ }<br>
+ def NotFP : FPFormat<0>;<br>
+ def ZeroArgFP : FPFormat<1>;<br>
+ def OneArgFP : FPFormat<2>;<br>
+ def OneArgFPRW : FPFormat<3>;<br>
+ def TwoArgFP : FPFormat<4>;<br>
+ def CompareFP : FPFormat<5>;<br>
+ def CondMovFP : FPFormat<6>;<br>
+ def SpecialFP : FPFormat<7>;<br>
+<br>
+In this case, template arguments are used as a space efficient way to specify a<br>
+list of "enumeration values", each with a "``Value``" field set to the specified<br>
+integer.<br>
+<br>
+The more esoteric forms of `TableGen expressions`_ are useful in conjunction<br>
+with template arguments. As an example:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class ModRefVal<bits<2> val> {<br>
+ bits<2> Value = val;<br>
+ }<br>
+<br>
+ def None : ModRefVal<0>;<br>
+ def Mod : ModRefVal<1>;<br>
+ def Ref : ModRefVal<2>;<br>
+ def ModRef : ModRefVal<3>;<br>
+<br>
+ class Value<ModRefVal MR> {<br>
+ // Decode some information into a more convenient format, while providing<br>
+ // a nice interface to the user of the "Value" class.<br>
+ bit isMod = MR.Value{0};<br>
+ bit isRef = MR.Value{1};<br>
+<br>
+ // other stuff...<br>
+ }<br>
+<br>
+ // Example uses<br>
+ def bork : Value<Mod>;<br>
+ def zork : Value<Ref>;<br>
+ def hork : Value<ModRef>;<br>
+<br>
+This is obviously a contrived example, but it shows how template arguments can<br>
+be used to decouple the interface provided to the user of the class from the<br>
+actual internal data representation expected by the class. In this case,<br>
+running ``llvm-tblgen`` on the example prints the following definitions:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ def bork { // Value<br>
+ bit isMod = 1;<br>
+ bit isRef = 0;<br>
+ }<br>
+ def hork { // Value<br>
+ bit isMod = 1;<br>
+ bit isRef = 1;<br>
+ }<br>
+ def zork { // Value<br>
+ bit isMod = 0;<br>
+ bit isRef = 1;<br>
+ }<br>
+<br>
+This shows that TableGen was able to dig into the argument and extract a piece<br>
+of information that was requested by the designer of the "Value" class. For<br>
+more realistic examples, please see existing users of TableGen, such as the X86<br>
+backend.<br>
+<br>
+Multiclass definitions and instances<br>
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^<br>
+<br>
+While classes with template arguments are a good way to factor commonality<br>
+between two instances of a definition, multiclasses allow a convenient notation<br>
+for defining multiple definitions at once (instances of implicitly constructed<br>
+classes). For example, consider an 3-address instruction set whose instructions<br>
+come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"<br>
+(e.g. SPARC). In this case, you'd like to specify in one place that this<br>
+commonality exists, then in a separate place indicate what all the ops are.<br>
+<br>
+Here is an example TableGen fragment that shows this idea:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ def ops;<br>
+ def GPR;<br>
+ def Imm;<br>
+ class inst<int opc, string asmstr, dag operandlist>;<br>
+<br>
+ multiclass ri_inst<int opc, string asmstr> {<br>
+ def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),<br>
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;<br>
+ def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),<br>
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;<br>
+ }<br>
+<br>
+ // Instantiations of the ri_inst multiclass.<br>
+ defm ADD : ri_inst<0b111, "add">;<br>
+ defm SUB : ri_inst<0b101, "sub">;<br>
+ defm MUL : ri_inst<0b100, "mul">;<br>
+ ...<br>
+<br>
+The name of the resultant definitions has the multidef fragment names appended<br>
+to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may<br>
+inherit from multiple multiclasses, instantiating definitions from each<br>
+multiclass. Using a multiclass this way is exactly equivalent to instantiating<br>
+the classes multiple times yourself, e.g. by writing:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ def ops;<br>
+ def GPR;<br>
+ def Imm;<br>
+ class inst<int opc, string asmstr, dag operandlist>;<br>
+<br>
+ class rrinst<int opc, string asmstr><br>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),<br>
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;<br>
+<br>
+ class riinst<int opc, string asmstr><br>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),<br>
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;<br>
+<br>
+ // Instantiations of the ri_inst multiclass.<br>
+ def ADD_rr : rrinst<0b111, "add">;<br>
+ def ADD_ri : riinst<0b111, "add">;<br>
+ def SUB_rr : rrinst<0b101, "sub">;<br>
+ def SUB_ri : riinst<0b101, "sub">;<br>
+ def MUL_rr : rrinst<0b100, "mul">;<br>
+ def MUL_ri : riinst<0b100, "mul">;<br>
+ ...<br>
+<br>
+A ``defm`` can also be used inside a multiclass providing several levels of<br>
+multiclass instantiations.<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class Instruction<bits<4> opc, string Name> {<br>
+ bits<4> opcode = opc;<br>
+ string name = Name;<br>
+ }<br>
+<br>
+ multiclass basic_r<bits<4> opc> {<br>
+ def rr : Instruction<opc, "rr">;<br>
+ def rm : Instruction<opc, "rm">;<br>
+ }<br>
+<br>
+ multiclass basic_s<bits<4> opc> {<br>
+ defm SS : basic_r<opc>;<br>
+ defm SD : basic_r<opc>;<br>
+ def X : Instruction<opc, "x">;<br>
+ }<br>
+<br>
+ multiclass basic_p<bits<4> opc> {<br>
+ defm PS : basic_r<opc>;<br>
+ defm PD : basic_r<opc>;<br>
+ def Y : Instruction<opc, "y">;<br>
+ }<br>
+<br>
+ defm ADD : basic_s<0xf>, basic_p<0xf>;<br>
+ ...<br>
+<br>
+ // Results<br>
+ def ADDPDrm { ...<br>
+ def ADDPDrr { ...<br>
+ def ADDPSrm { ...<br>
+ def ADDPSrr { ...<br>
+ def ADDSDrm { ...<br>
+ def ADDSDrr { ...<br>
+ def ADDY { ...<br>
+ def ADDX { ...<br>
+<br>
+``defm`` declarations can inherit from classes too, the rule to follow is that<br>
+the class list must start after the last multiclass, and there must be at least<br>
+one multiclass before them.<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class XD { bits<4> Prefix = 11; }<br>
+ class XS { bits<4> Prefix = 12; }<br>
+<br>
+ class I<bits<4> op> {<br>
+ bits<4> opcode = op;<br>
+ }<br>
+<br>
+ multiclass R {<br>
+ def rr : I<4>;<br>
+ def rm : I<2>;<br>
+ }<br>
+<br>
+ multiclass Y {<br>
+ defm SS : R, XD;<br>
+ defm SD : R, XS;<br>
+ }<br>
+<br>
+ defm Instr : Y;<br>
+<br>
+ // Results<br>
+ def InstrSDrm {<br>
+ bits<4> opcode = { 0, 0, 1, 0 };<br>
+ bits<4> Prefix = { 1, 1, 0, 0 };<br>
+ }<br>
+ ...<br>
+ def InstrSSrr {<br>
+ bits<4> opcode = { 0, 1, 0, 0 };<br>
+ bits<4> Prefix = { 1, 0, 1, 1 };<br>
+ }<br>
+<br>
+File scope entities<br>
+-------------------<br>
+<br>
+File inclusion<br>
+^^^^^^^^^^^^^^<br>
+<br>
+TableGen supports the '``include``' token, which textually substitutes the<br>
+specified file in place of the include directive. The filename should be<br>
+specified as a double quoted string immediately after the '``include``' keyword.<br>
+Example:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ include "<a href="http://foo.td" target="_blank">foo.td</a>"<br>
+<br>
+'let' expressions<br>
+^^^^^^^^^^^^^^^^^<br>
+<br>
+"Let" expressions at file scope are similar to `"let" expressions within a<br>
+record`_, except they can specify a value binding for multiple records at a<br>
+time, and may be useful in certain other cases. File-scope let expressions are<br>
+really just another way that TableGen allows the end-user to factor out<br>
+commonality from the records.<br>
+<br>
+File-scope "let" expressions take a comma-separated list of bindings to apply,<br>
+and one or more records to bind the values in. Here are some examples:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in<br>
+ def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;<br>
+<br>
+ let isCall = 1 in<br>
+ // All calls clobber the non-callee saved registers...<br>
+ let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,<br>
+ MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,<br>
+ XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {<br>
+ def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),<br>
+ "call\t${dst:call}", []>;<br>
+ def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),<br>
+ "call\t{*}$dst", [(X86call GR32:$dst)]>;<br>
+ def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),<br>
+ "call\t{*}$dst", []>;<br>
+ }<br>
+<br>
+File-scope "let" expressions are often useful when a couple of definitions need<br>
+to be added to several records, and the records do not otherwise need to be<br>
+opened, as in the case with the ``CALL*`` instructions above.<br>
+<br>
+It's also possible to use "let" expressions inside multiclasses, providing more<br>
+ways to factor out commonality from the records, specially if using several<br>
+levels of multiclass instantiations. This also avoids the need of using "let"<br>
+expressions within subsequent records inside a multiclass.<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ multiclass basic_r<bits<4> opc> {<br>
+ let Predicates = [HasSSE2] in {<br>
+ def rr : Instruction<opc, "rr">;<br>
+ def rm : Instruction<opc, "rm">;<br>
+ }<br>
+ let Predicates = [HasSSE3] in<br>
+ def rx : Instruction<opc, "rx">;<br>
+ }<br>
+<br>
+ multiclass basic_ss<bits<4> opc> {<br>
+ let IsDouble = 0 in<br>
+ defm SS : basic_r<opc>;<br>
+<br>
+ let IsDouble = 1 in<br>
+ defm SD : basic_r<opc>;<br>
+ }<br>
+<br>
+ defm ADD : basic_ss<0xf>;<br>
+<br>
+Looping<br>
+^^^^^^^<br>
+<br>
+TableGen supports the '``foreach``' block, which textually replicates the loop<br>
+body, substituting iterator values for iterator references in the body.<br>
+Example:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ foreach i = [0, 1, 2, 3] in {<br>
+ def R#i : Register<...>;<br>
+ def F#i : Register<...>;<br>
+ }<br>
+<br>
+This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks<br>
+may be nested. If there is only one item in the body the braces may be<br>
+elided:<br>
<br>
-.. productionlist::<br>
- SimpleValue: `TokIdentifier`<br>
+.. code-block:: llvm<br>
<br>
-The value will be the variable referenced by the identifier. It can be one<br>
-of:<br>
+ foreach i = [0, 1, 2, 3] in<br>
+ def R#i : Register<...>;<br>
<br>
-.. The code for this is exceptionally abstruse. These examples are a<br>
- best-effort attempt.<br>
-<br>
-* name of a ``def``, such as the use of ``Bar`` in::<br>
-<br>
- def Bar : SomeClass {<br>
- int X = 5;<br>
- }<br>
-<br>
- def Foo {<br>
- SomeClass Baz = Bar;<br>
- }<br>
-<br>
-* value local to a ``def``, such as the use of ``Bar`` in::<br>
-<br>
- def Foo {<br>
- int Bar = 5;<br>
- int Baz = Bar;<br>
- }<br>
-<br>
-* a template arg of a ``class``, such as the use of ``Bar`` in::<br>
-<br>
- class Foo<int Bar> {<br>
- int Baz = Bar;<br>
- }<br>
-<br>
-* value local to a ``multiclass``, such as the use of ``Bar`` in::<br>
-<br>
- multiclass Foo {<br>
- int Bar = 5;<br>
- int Baz = Bar;<br>
- }<br>
-<br>
-* a template arg to a ``multiclass``, such as the use of ``Bar`` in::<br>
-<br>
- multiclass Foo<int Bar> {<br>
- int Baz = Bar;<br>
- }<br>
-<br>
-.. productionlist::<br>
- SimpleValue: `TokInteger`<br>
-<br>
-This represents the numeric value of the integer.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: `TokString`+<br>
-<br>
-Multiple adjacent string literals are concatenated like in C/C++. The value<br>
-is the concatenation of the strings.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: `TokCodeFragment`<br>
-<br>
-The value is the string value of the code fragment.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: "?"<br>
-<br>
-``?`` represents an "unset" initializer.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: "{" `ValueList` "}"<br>
- ValueList: [`ValueListNE`]<br>
- ValueListNE: `Value` ("," `Value`)*<br>
-<br>
-This represents a sequence of bits, as would be used to initialize a<br>
-``bits<n>`` field (where ``n`` is the number of bits).<br>
-<br>
-.. productionlist::<br>
- SimpleValue: `ClassID` "<" `ValueListNE` ">"<br>
-<br>
-This generates a new anonymous record definition (as would be created by an<br>
-unnamed ``def`` inheriting from the given class with the given template<br>
-arguments) and the value is the value of that record definition.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]<br>
-<br>
-A list initializer. The optional :token:`Type` can be used to indicate a<br>
-specific element type, otherwise the element type will be deduced from the<br>
-given values.<br>
-<br>
-.. The initial `DagArg` of the dag must start with an identifier or<br>
- !cast, but this is more of an implementation detail and so for now just<br>
- leave it out.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: "(" `DagArg` `DagArgList` ")"<br>
- DagArgList: `DagArg` ("," `DagArg`)*<br>
- DagArg: `Value` [":" `TokVarName`] | `TokVarName`<br>
-<br>
-The initial :token:`DagArg` is called the "operator" of the dag.<br>
-<br>
-.. productionlist::<br>
- SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"<br>
-<br>
-Bodies<br>
-------<br>
-<br>
-.. productionlist::<br>
- ObjectBody: `BaseClassList` `Body`<br>
- BaseClassList: [":" `BaseClassListNE`]<br>
- BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*<br>
- SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]<br>
- DefmID: `TokIdentifier`<br>
-<br>
-The version with the :token:`MultiClassID` is only valid in the<br>
-:token:`BaseClassList` of a ``defm``.<br>
-The :token:`MultiClassID` should be the name of a ``multiclass``.<br>
-<br>
-.. put this somewhere else<br>
-<br>
-It is after parsing the base class list that the "let stack" is applied.<br>
-<br>
-.. productionlist::<br>
- Body: ";" | "{" BodyList "}"<br>
- BodyList: BodyItem*<br>
- BodyItem: `Declaration` ";"<br>
- :| "let" `TokIdentifier` [`RangeList`] "=" `Value` ";"<br>
-<br>
-The ``let`` form allows overriding the value of an inherited field.<br>
-<br>
-``def``<br>
--------<br>
-<br>
-.. TODO::<br>
- There can be pastes in the names here, like ``#NAME#``. Look into that<br>
- and document it (it boils down to ParseIDValue with IDParseMode ==<br>
- ParseNameMode). ParseObjectName calls into the general ParseValue, with<br>
- the only different from "arbitrary expression parsing" being IDParseMode<br>
- == Mode.<br>
-<br>
-.. productionlist::<br>
- Def: "def" `TokIdentifier` `ObjectBody`<br>
-<br>
-Defines a record whose name is given by the :token:`TokIdentifier`. The<br>
-fields of the record are inherited from the base classes and defined in the<br>
-body.<br>
-<br>
-Special handling occurs if this ``def`` appears inside a ``multiclass`` or<br>
-a ``foreach``.<br>
-<br>
-``defm``<br>
---------<br>
-<br>
-.. productionlist::<br>
- Defm: "defm" `TokIdentifier` ":" `BaseClassListNE` ";"<br>
-<br>
-Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must<br>
-precede any ``class``'s that appear.<br>
-<br>
-``foreach``<br>
------------<br>
-<br>
-.. productionlist::<br>
- Foreach: "foreach" `Declaration` "in" "{" `Object`* "}"<br>
- :| "foreach" `Declaration` "in" `Object`<br>
-<br>
-The value assigned to the variable in the declaration is iterated over and<br>
-the object or object list is reevaluated with the variable set at each<br>
-iterated value.<br>
-<br>
-Top-Level ``let``<br>
------------------<br>
-<br>
-.. productionlist::<br>
- Let: "let" `LetList` "in" "{" `Object`* "}"<br>
- :| "let" `LetList` "in" `Object`<br>
- LetList: `LetItem` ("," `LetItem`)*<br>
- LetItem: `TokIdentifier` [`RangeList`] "=" `Value`<br>
+Code Generator backend info<br>
+===========================<br>
<br>
-This is effectively equivalent to ``let`` inside the body of a record<br>
-except that it applies to multiple records at a time. The bindings are<br>
-applied at the end of parsing the base classes of a record.<br>
+Expressions used by code generator to describe instructions and isel patterns:<br>
<br>
-``multiclass``<br>
---------------<br>
+``(implicit a)``<br>
+ an implicitly defined physical register. This tells the dag instruction<br>
+ selection emitter the input pattern's extra definitions matches implicit<br>
+ physical register definitions.<br>
<br>
-.. productionlist::<br>
- MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]<br>
- : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"<br>
- BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*<br>
- MultiClassID: `TokIdentifier`<br>
- MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`<br>
<br>
Added: llvm/trunk/docs/TableGen/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/index.rst?rev=204351&view=auto" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGen/index.rst?rev=204351&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/TableGen/index.rst (added)<br>
+++ llvm/trunk/docs/TableGen/index.rst Thu Mar 20 11:08:34 2014<br>
@@ -0,0 +1,306 @@<br>
+========<br>
+TableGen<br>
+========<br>
+<br>
+.. contents::<br>
+ :local:<br>
+<br>
+.. toctree::<br>
+ :hidden:<br>
+<br>
+ BackEnds<br>
+ LangRef<br>
+ Deficiencies<br>
+<br>
+Introduction<br>
+============<br>
+<br>
+TableGen's purpose is to help a human develop and maintain records of<br>
+domain-specific information. Because there may be a large number of these<br>
+records, it is specifically designed to allow writing flexible descriptions and<br>
+for common features of these records to be factored out. This reduces the<br>
+amount of duplication in the description, reduces the chance of error, and makes<br>
+it easier to structure domain specific information.<br>
+<br>
+The core part of TableGen parses a file, instantiates the declarations, and<br>
+hands the result off to a domain-specific `backends`_ for processing.<br>
+<br>
+The current major users of TableGen are :doc:`../CodeGenerator`<br>
+and the<br>
+`Clang diagnostics and attributes <<a href="http://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings" target="_blank">http://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings</a>>`_.<br>
+<br>
+Note that if you work on TableGen much, and use emacs or vim, that you can find<br>
+an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and<br>
+``llvm/utils/vim`` directories of your LLVM distribution, respectively.<br>
+<br>
+.. _intro:<br>
+<br>
+<br>
+The TableGen program<br>
+====================<br>
+<br>
+TableGen files are interpreted by the TableGen program: `llvm-tblgen` available<br>
+on your build directory under `bin`. It is not installed in the system (or where<br>
+your sysroot is set to), since it has no use beyond LLVM's build process.<br>
+<br>
+Running TableGen<br>
+----------------<br>
+<br>
+TableGen runs just like any other LLVM tool. The first (optional) argument<br>
+specifies the file to read. If a filename is not specified, ``llvm-tblgen``<br>
+reads from standard input.<br>
+<br>
+To be useful, one of the `backends`_ must be used. These backends are<br>
+selectable on the command line (type '``llvm-tblgen -help``' for a list). For<br>
+example, to get a list of all of the definitions that subclass a particular type<br>
+(which can be useful for building up an enum list of these records), use the<br>
+``-print-enums`` option:<br>
+<br>
+.. code-block:: bash<br>
+<br>
+ $ llvm-tblgen X86.td -print-enums -class=Register<br>
+ AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,<br>
+ ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,<br>
+ MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,<br>
+ R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,<br>
+ R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,<br>
+ RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,<br>
+ XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,<br>
+ XMM6, XMM7, XMM8, XMM9,<br>
+<br>
+ $ llvm-tblgen X86.td -print-enums -class=Instruction<br>
+ ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,<br>
+ ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,<br>
+ ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,<br>
+ ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,<br>
+ ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...<br>
+<br>
+The default backend prints out all of the records.<br>
+<br>
+If you plan to use TableGen, you will most likely have to write a `backend`_<br>
+that extracts the information specific to what you need and formats it in the<br>
+appropriate way.<br>
+<br>
+Example<br>
+-------<br>
+<br>
+With no other arguments, `llvm-tblgen` parses the specified file and prints out all<br>
+of the classes, then all of the definitions. This is a good way to see what the<br>
+various definitions expand to fully. Running this on the ``X86.td`` file prints<br>
+this (at the time of this writing):<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ ...<br>
+ def ADD32rr { // Instruction X86Inst I<br>
+ string Namespace = "X86";<br>
+ dag OutOperandList = (outs GR32:$dst);<br>
+ dag InOperandList = (ins GR32:$src1, GR32:$src2);<br>
+ string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";<br>
+ list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];<br>
+ list<Register> Uses = [];<br>
+ list<Register> Defs = [EFLAGS];<br>
+ list<Predicate> Predicates = [];<br>
+ int CodeSize = 3;<br>
+ int AddedComplexity = 0;<br>
+ bit isReturn = 0;<br>
+ bit isBranch = 0;<br>
+ bit isIndirectBranch = 0;<br>
+ bit isBarrier = 0;<br>
+ bit isCall = 0;<br>
+ bit canFoldAsLoad = 0;<br>
+ bit mayLoad = 0;<br>
+ bit mayStore = 0;<br>
+ bit isImplicitDef = 0;<br>
+ bit isConvertibleToThreeAddress = 1;<br>
+ bit isCommutable = 1;<br>
+ bit isTerminator = 0;<br>
+ bit isReMaterializable = 0;<br>
+ bit isPredicable = 0;<br>
+ bit hasDelaySlot = 0;<br>
+ bit usesCustomInserter = 0;<br>
+ bit hasCtrlDep = 0;<br>
+ bit isNotDuplicable = 0;<br>
+ bit hasSideEffects = 0;<br>
+ bit neverHasSideEffects = 0;<br>
+ InstrItinClass Itinerary = NoItinerary;<br>
+ string Constraints = "";<br>
+ string DisableEncoding = "";<br>
+ bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };<br>
+ Format Form = MRMDestReg;<br>
+ bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };<br>
+ ImmType ImmT = NoImm;<br>
+ bits<3> ImmTypeBits = { 0, 0, 0 };<br>
+ bit hasOpSizePrefix = 0;<br>
+ bit hasAdSizePrefix = 0;<br>
+ bits<4> Prefix = { 0, 0, 0, 0 };<br>
+ bit hasREX_WPrefix = 0;<br>
+ FPFormat FPForm = ?;<br>
+ bits<3> FPFormBits = { 0, 0, 0 };<br>
+ }<br>
+ ...<br>
+<br>
+This definition corresponds to the 32-bit register-register ``add`` instruction<br>
+of the x86 architecture. ``def ADD32rr`` defines a record named<br>
+``ADD32rr``, and the comment at the end of the line indicates the superclasses<br>
+of the definition. The body of the record contains all of the data that<br>
+TableGen assembled for the record, indicating that the instruction is part of<br>
+the "X86" namespace, the pattern indicating how the instruction should be<br>
+emitted into the assembly file, that it is a two-address instruction, has a<br>
+particular encoding, etc. The contents and semantics of the information in the<br>
+record are specific to the needs of the X86 backend, and are only shown as an<br>
+example.<br>
+<br>
+As you can see, a lot of information is needed for every instruction supported<br>
+by the code generator, and specifying it all manually would be unmaintainable,<br>
+prone to bugs, and tiring to do in the first place. Because we are using<br>
+TableGen, all of the information was derived from the following definition:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ let Defs = [EFLAGS],<br>
+ isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y<br>
+ isConvertibleToThreeAddress = 1 in // Can transform into LEA.<br>
+ def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),<br>
+ (ins GR32:$src1, GR32:$src2),<br>
+ "add{l}\t{$src2, $dst|$dst, $src2}",<br>
+ [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;<br>
+<br>
+This definition makes use of the custom class ``I`` (extended from the custom<br>
+class ``X86Inst``), which is defined in the X86-specific TableGen file, to<br>
+factor out the common features that instructions of its class share. A key<br>
+feature of TableGen is that it allows the end-user to define the abstractions<br>
+they prefer to use when describing their information.<br>
+<br>
+Each ``def`` record has a special entry called "NAME". This is the name of the<br>
+record ("``ADD32rr``" above). In the general case ``def`` names can be formed<br>
+from various kinds of string processing expressions and ``NAME`` resolves to the<br>
+final value obtained after resolving all of those expressions. The user may<br>
+refer to ``NAME`` anywhere she desires to use the ultimate name of the ``def``.<br>
+``NAME`` should not be defined anywhere else in user code to avoid conflicts.<br>
+<br>
+Syntax<br>
+======<br>
+<br>
+TableGen has a syntax that is losely based on C++ templates, with built-in<br>
+types and specification. In addition, TableGen's syntax introduces some<br>
+automation concepts like multiclass, foreach, let, etc.<br>
+<br>
+Basic concepts<br>
+--------------<br>
+<br>
+TableGen files consist of two key parts: 'classes' and 'definitions', both of<br>
+which are considered 'records'.<br>
+<br>
+**TableGen records** have a unique name, a list of values, and a list of<br>
+superclasses. The list of values is the main data that TableGen builds for each<br>
+record; it is this that holds the domain specific information for the<br>
+application. The interpretation of this data is left to a specific `backends`_,<br>
+but the structure and format rules are taken care of and are fixed by<br>
+TableGen.<br>
+<br>
+**TableGen definitions** are the concrete form of 'records'. These generally do<br>
+not have any undefined values, and are marked with the '``def``' keyword.<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",<br>
+ "Enable ARMv8 FP">;<br>
+<br>
+In this example, FeatureFPARMv8 is ``SubtargetFeature`` record initialised<br>
+with some values. The names of the classes are defined via the<br>
+keyword `class` either on the same file or some other included. Most target<br>
+TableGen files include the generic ones in ``include/llvm/Target``.<br>
+<br>
+**TableGen classes** are abstract records that are used to build and describe<br>
+other records. These classes allow the end-user to build abstractions for<br>
+either the domain they are targeting (such as "Register", "RegisterClass", and<br>
+"Instruction" in the LLVM code generator) or for the implementor to help factor<br>
+out common properties of records (such as "FPInst", which is used to represent<br>
+floating point instructions in the X86 backend). TableGen keeps track of all of<br>
+the classes that are used to build up a definition, so the backend can find all<br>
+definitions of a particular class, such as "Instruction".<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ class ProcNoItin<string Name, list<SubtargetFeature> Features><br>
+ : Processor<Name, NoItineraries, Features>;<br>
+<br>
+Here, the class ProcNoItin, receiving parameters `Name` of type `string` and<br>
+a list of target features is specializing the class Processor by passing the<br>
+arguments down as well as hard-coding NoItineraries.<br>
+<br>
+**TableGen multiclasses** are groups of abstract records that are instantiated<br>
+all at once. Each instantiation can result in multiple TableGen definitions.<br>
+If a multiclass inherits from another multiclass, the definitions in the<br>
+sub-multiclass become part of the current multiclass, as if they were declared<br>
+in the current multiclass.<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ multiclass ro_signed_pats<string T, string Rm, dag Base, dag Offset, dag Extend,<br>
+ dag address, ValueType sty> {<br>
+ def : Pat<(i32 (!cast<SDNode>("sextload" # sty) address)),<br>
+ (!cast<Instruction>("LDRS" # T # "w_" # Rm # "_RegOffset")<br>
+ Base, Offset, Extend)>;<br>
+<br>
+ def : Pat<(i64 (!cast<SDNode>("sextload" # sty) address)),<br>
+ (!cast<Instruction>("LDRS" # T # "x_" # Rm # "_RegOffset")<br>
+ Base, Offset, Extend)>;<br>
+ }<br>
+<br>
+ defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,<br>
+ !foreach(decls.pattern, address,<br>
+ !subst(SHIFT, imm_eq0, decls.pattern)),<br>
+ i8>;<br>
+<br>
+<br>
+<br>
+See the `TableGen Language Reference <LangRef.html>`_ for more information.<br>
+<br>
+.. _backend:<br>
+.. _backends:<br>
+<br>
+TableGen backends<br>
+=================<br>
+<br>
+TableGen files have no real meaning without a back-end. The default operation<br>
+of running ``llvm-tblgen`` is to print the information in a textual format, but<br>
+that's only useful for debugging of the TableGen files themselves. The power<br>
+in TableGen is, however, to interpret the source files into an internal<br>
+representation that can be generated into anything you want.<br>
+<br>
+Current usage of TableGen is to create include huge files with tables that you<br>
+can either include directly (if the output is in the language you're coding),<br>
+or be used in pre-processing via macros surrounding the include of the file.<br>
+<br>
+Direct output can be used if the back-end already prints a table in C format<br>
+or if the output is just a list of strings (for error and warning messages).<br>
+Pre-processed output should be used if the same information needs to be used<br>
+in different contexts (like Instruction names), so your back-end should print<br>
+a meta-information list that can be shaped into different compile-time formats.<br>
+<br>
+See the `TableGen BackEnds <BackEnds.html>`_ for more information.<br>
+<br>
+TableGen Deficiencies<br>
+=====================<br>
+<br>
+Despite being very generic, TableGen has some deficiencies that have been<br>
+pointed out numerous times. The common theme is that, while TableGen allows<br>
+you to build Domain-Specific-Languages, the final languages that you create<br>
+lack the power of other DSLs, which in turn increase considerably the size<br>
+and complecity of TableGen files.<br>
+<br>
+At the same time, TableGen allows you to create virtually any meaning of<br>
+the basic concepts via custom-made back-ends, which can pervert the original<br>
+design and make it very hard for newcomers to understand the evil TableGen<br>
+file.<br>
+<br>
+There are some in favour of extending the semantics even more, but makeing sure<br>
+back-ends adhere to strict rules. Others suggesting we should move to less,<br>
+more powerful DSLs designed with specific purposes, or even re-using existing<br>
+DSLs.<br>
+<br>
+Either way, this is a discussion that is likely spanning across several years,<br>
+if not decades. You can read more in the `TableGen Deficiencies <Deficiencies.html>`_<br>
+document.<br>
<br>
Modified: llvm/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=204351&r1=204350&r2=204351&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=204351&r1=204350&r2=204351&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/index.rst (original)<br>
+++ llvm/trunk/docs/index.rst Thu Mar 20 11:08:34 2014<br>
@@ -222,6 +222,7 @@ For API clients and LLVM developers.<br>
LinkTimeOptimization<br>
SegmentedStacks<br>
TableGenFundamentals<br>
+ TableGen/index<br>
DebuggingJITedCode<br>
GoldPlugin<br>
MarkedUpDisassembly<br>
@@ -231,7 +232,6 @@ For API clients and LLVM developers.<br>
WritingAnLLVMBackend<br>
GarbageCollection<br>
WritingAnLLVMPass<br>
- TableGen/LangRef<br>
HowToUseAttributes<br>
NVPTXUsage<br>
StackMaps<br>
<br>
<br>
_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@cs.uiuc.edu">llvm-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
</blockquote></div><br></div></div></div>