[llvm-commits] [llvm] r158903 - in /llvm/trunk/docs: TableGenFundamentals.html TableGenFundamentals.rst subsystems.rst

Bill Wendling isanbard at gmail.com
Wed Jun 20 23:58:24 PDT 2012


Author: void
Date: Thu Jun 21 01:58:24 2012
New Revision: 158903

URL: http://llvm.org/viewvc/llvm-project?rev=158903&view=rev
Log:
Sphinxify the tablegen document.

Added:
    llvm/trunk/docs/TableGenFundamentals.rst
Removed:
    llvm/trunk/docs/TableGenFundamentals.html
Modified:
    llvm/trunk/docs/subsystems.rst

Removed: llvm/trunk/docs/TableGenFundamentals.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGenFundamentals.html?rev=158902&view=auto
==============================================================================
--- llvm/trunk/docs/TableGenFundamentals.html (original)
+++ llvm/trunk/docs/TableGenFundamentals.html (removed)
@@ -1,978 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
-                      "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-  <title>TableGen Fundamentals</title>
-  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
-</head>
-<body>
-
-<h1>TableGen Fundamentals</h1>
-
-<div>
-<ul>
-  <li><a href="#introduction">Introduction</a>
-  <ol>
-    <li><a href="#concepts">Basic concepts</a></li>
-    <li><a href="#example">An example record</a></li>
-    <li><a href="#running">Running TableGen</a></li>
-  </ol></li>
-  <li><a href="#syntax">TableGen syntax</a>
-  <ol>
-    <li><a href="#primitives">TableGen primitives</a>
-    <ol>
-      <li><a href="#comments">TableGen comments</a></li>
-      <li><a href="#types">The TableGen type system</a></li>
-      <li><a href="#values">TableGen values and expressions</a></li>
-    </ol></li>
-    <li><a href="#classesdefs">Classes and definitions</a>
-    <ol>
-      <li><a href="#valuedef">Value definitions</a></li>
-      <li><a href="#recordlet">'let' expressions</a></li>
-      <li><a href="#templateargs">Class template arguments</a></li>
-      <li><a href="#multiclass">Multiclass definitions and instances</a></li>
-    </ol></li>
-    <li><a href="#filescope">File scope entities</a>
-    <ol>
-      <li><a href="#include">File inclusion</a></li>
-      <li><a href="#globallet">'let' expressions</a></li>
-      <li><a href="#foreach">'foreach' blocks</a></li>
-    </ol></li>
-  </ol></li>
-  <li><a href="#backends">TableGen backends</a>
-  <ol>
-    <li><a href="#">todo</a></li>
-  </ol></li>
-</ul>
-</div>
-
-<div class="doc_author">
-  <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="introduction">Introduction</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>TableGen's purpose is to help a human develop and maintain records of
-domain-specific information.  Because there may be a large number of these
-records, it is specifically designed to allow writing flexible descriptions and
-for common features of these records to be factored out.  This reduces the
-amount of duplication in the description, reduces the chance of error, and
-makes it easier to structure domain specific information.</p>
-
-<p>The core part of TableGen <a href="#syntax">parses a file</a>, instantiates
-the declarations, and hands the result off to a domain-specific "<a
-href="#backends">TableGen backend</a>" for processing.  The current major user
-of TableGen is the <a href="CodeGenerator.html">LLVM code generator</a>.</p>
-
-<p>Note that if you work on TableGen much, and use emacs or vim, that you can
-find an emacs "TableGen mode" and a vim language file in the
-<tt>llvm/utils/emacs</tt> and <tt>llvm/utils/vim</tt> directories of your LLVM
-distribution, respectively.</p>
-
-<!-- ======================================================================= -->
-<h3><a name="concepts">Basic concepts</a></h3>
-
-<div>
-
-<p>TableGen files consist of two key parts: 'classes' and 'definitions', both
-of which are considered 'records'.</p>
-
-<p><b>TableGen records</b> have a unique name, a list of values, and a list of
-superclasses.  The list of values is the main data that TableGen builds for each
-record; it is this that holds the domain specific information for the
-application.  The interpretation of this data is left to a specific <a
-href="#backends">TableGen backend</a>, but the structure and format rules are
-taken care of and are fixed by TableGen.</p>
-
-<p><b>TableGen definitions</b> are the concrete form of 'records'.  These
-generally do not have any undefined values, and are marked with the
-'<tt>def</tt>' keyword.</p>
-
-<p><b>TableGen classes</b> are abstract records that are used to build and
-describe other records.  These 'classes' allow the end-user to build
-abstractions for either the domain they are targeting (such as "Register",
-"RegisterClass", and "Instruction" in the LLVM code generator) or for the
-implementor to help factor out common properties of records (such as "FPInst",
-which is used to represent floating point instructions in the X86 backend).
-TableGen keeps track of all of the classes that are used to build up a
-definition, so the backend can find all definitions of a particular class, such
-as "Instruction".</p>
-
-<p><b>TableGen multiclasses</b> are groups of abstract records that are
-instantiated all at once.  Each instantiation can result in multiple
-TableGen definitions.  If a multiclass inherits from another multiclass,
-the definitions in the sub-multiclass become part of the current
-multiclass, as if they were declared in the current multiclass.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="example">An example record</a></h3>
-
-<div>
-
-<p>With no other arguments, TableGen parses the specified file and prints out
-all of the classes, then all of the definitions.  This is a good way to see what
-the various definitions expand to fully.  Running this on the <tt>X86.td</tt>
-file prints this (at the time of this writing):</p>
-
-<div class="doc_code">
-<pre>
-...
-<b>def</b> ADD32rr {   <i>// Instruction X86Inst I</i>
-  <b>string</b> Namespace = "X86";
-  <b>dag</b> OutOperandList = (outs GR32:$dst);
-  <b>dag</b> InOperandList = (ins GR32:$src1, GR32:$src2);
-  <b>string</b> AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
-  <b>list</b><dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
-  <b>list</b><Register> Uses = [];
-  <b>list</b><Register> Defs = [EFLAGS];
-  <b>list</b><Predicate> Predicates = [];
-  <b>int</b> CodeSize = 3;
-  <b>int</b> AddedComplexity = 0;
-  <b>bit</b> isReturn = 0;
-  <b>bit</b> isBranch = 0;
-  <b>bit</b> isIndirectBranch = 0;
-  <b>bit</b> isBarrier = 0;
-  <b>bit</b> isCall = 0;
-  <b>bit</b> canFoldAsLoad = 0;
-  <b>bit</b> mayLoad = 0;
-  <b>bit</b> mayStore = 0;
-  <b>bit</b> isImplicitDef = 0;
-  <b>bit</b> isConvertibleToThreeAddress = 1;
-  <b>bit</b> isCommutable = 1;
-  <b>bit</b> isTerminator = 0;
-  <b>bit</b> isReMaterializable = 0;
-  <b>bit</b> isPredicable = 0;
-  <b>bit</b> hasDelaySlot = 0;
-  <b>bit</b> usesCustomInserter = 0;
-  <b>bit</b> hasCtrlDep = 0;
-  <b>bit</b> isNotDuplicable = 0;
-  <b>bit</b> hasSideEffects = 0;
-  <b>bit</b> neverHasSideEffects = 0;
-  InstrItinClass Itinerary = NoItinerary;
-  <b>string</b> Constraints = "";
-  <b>string</b> DisableEncoding = "";
-  <b>bits</b><8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
-  Format Form = MRMDestReg;
-  <b>bits</b><6> FormBits = { 0, 0, 0, 0, 1, 1 };
-  ImmType ImmT = NoImm;
-  <b>bits</b><3> ImmTypeBits = { 0, 0, 0 };
-  <b>bit</b> hasOpSizePrefix = 0;
-  <b>bit</b> hasAdSizePrefix = 0;
-  <b>bits</b><4> Prefix = { 0, 0, 0, 0 };
-  <b>bit</b> hasREX_WPrefix = 0;
-  FPFormat FPForm = ?;
-  <b>bits</b><3> FPFormBits = { 0, 0, 0 };
-}
-...
-</pre>
-</div>
-
-<p>This definition corresponds to a 32-bit register-register add instruction in
-the X86.  The string after the '<tt>def</tt>' string indicates the name of the
-record—"<tt>ADD32rr</tt>" in this case—and the comment at the end of
-the line indicates the superclasses of the definition.  The body of the record
-contains all of the data that TableGen assembled for the record, indicating that
-the instruction is part of the "X86" namespace, the pattern indicating how the
-the instruction should be emitted into the assembly file, that it is a
-two-address instruction, has a particular encoding, etc.  The contents and
-semantics of the information in the record is specific to the needs of the X86
-backend, and is only shown as an example.</p>
-
-<p>As you can see, a lot of information is needed for every instruction
-supported by the code generator, and specifying it all manually would be
-unmaintainable, prone to bugs, and tiring to do in the first place.  Because we
-are using TableGen, all of the information was derived from the following
-definition:</p>
-
-<div class="doc_code">
-<pre>
-let Defs = [EFLAGS],
-    isCommutable = 1,                  <i>// X = ADD Y,Z --> X = ADD Z,Y</i>
-    isConvertibleToThreeAddress = 1 <b>in</b> <i>// Can transform into LEA.</i>
-def ADD32rr  : I<0x01, MRMDestReg, (outs GR32:$dst),
-                                   (ins GR32:$src1, GR32:$src2),
-                 "add{l}\t{$src2, $dst|$dst, $src2}",
-                 [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
-</pre>
-</div>
-
-<p>This definition makes use of the custom class <tt>I</tt> (extended from the
-custom class <tt>X86Inst</tt>), which is defined in the X86-specific TableGen
-file, to factor out the common features that instructions of its class share.  A
-key feature of TableGen is that it allows the end-user to define the
-abstractions they prefer to use when describing their information.</p>
-
-<p>Each def record has a special entry called "NAME."  This is the
-name of the def ("ADD32rr" above).  In the general case def names can
-be formed from various kinds of string processing expressions and NAME
-resolves to the final value obtained after resolving all of those
-expressions.  The user may refer to NAME anywhere she desires to use
-the ultimate name of the def.  NAME should not be defined anywhere
-else in user code to avoid conflict problems.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3><a name="running">Running TableGen</a></h3>
-
-<div>
-
-<p>TableGen runs just like any other LLVM tool.  The first (optional) argument
-specifies the file to read.  If a filename is not specified, 
-<tt>llvm-tblgen</tt> reads from standard input.</p>
-
-<p>To be useful, one of the <a href="#backends">TableGen backends</a> must be
-used.  These backends are selectable on the command line (type '<tt>llvm-tblgen
--help</tt>' for a list).  For example, to get a list of all of the definitions
-that subclass a particular type (which can be useful for building up an enum
-list of these records), use the <tt>-print-enums</tt> option:</p>
-
-<div class="doc_code">
-<pre>
-$ llvm-tblgen X86.td -print-enums -class=Register
-AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
-ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
-MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
-R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
-R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
-RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
-XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
-XMM6, XMM7, XMM8, XMM9,
-
-$ llvm-tblgen X86.td -print-enums -class=Instruction 
-ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
-ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
-ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
-ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
-ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
-</pre>
-</div>
-
-<p>The default backend prints out all of the records, as described <a
-href="#example">above</a>.</p>
-
-<p>If you plan to use TableGen, you will most likely have to <a
-href="#backends">write a backend</a> that extracts the information specific to
-what you need and formats it in the appropriate way.</p>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="syntax">TableGen syntax</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>TableGen doesn't care about the meaning of data (that is up to the backend to
-define), but it does care about syntax, and it enforces a simple type system.
-This section describes the syntax and the constructs allowed in a TableGen file.
-</p>
-
-<!-- ======================================================================= -->
-<h3><a name="primitives">TableGen primitives</a></h3>
-
-<div>
-
-<!-- -------------------------------------------------------------------------->
-<h4><a name="comments">TableGen comments</a></h4>
-
-<div>
-
-<p>TableGen supports BCPL style "<tt>//</tt>" comments, which run to the end of
-the line, and it also supports <b>nestable</b> "<tt>/* */</tt>" comments.</p>
-
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="types">The TableGen type system</a>
-</h4>
-
-<div>
-
-<p>TableGen files are strongly typed, in a simple (but complete) type-system.
-These types are used to perform automatic conversions, check for errors, and to
-help interface designers constrain the input that they allow.  Every <a
-href="#valuedef">value definition</a> is required to have an associated type.
-</p>
-
-<p>TableGen supports a mixture of very low-level types (such as <tt>bit</tt>)
-and very high-level types (such as <tt>dag</tt>).  This flexibility is what
-allows it to describe a wide range of information conveniently and compactly.
-The TableGen types are:</p>
-
-<dl>
-<dt><tt><b>bit</b></tt></dt>
-  <dd>A 'bit' is a boolean value that can hold either 0 or 1.</dd>
-
-<dt><tt><b>int</b></tt></dt>
-  <dd>The 'int' type represents a simple 32-bit integer value, such as 5.</dd>
-
-<dt><tt><b>string</b></tt></dt>
-  <dd>The 'string' type represents an ordered sequence of characters of
-  arbitrary length.</dd>
-
-<dt><tt><b>bits</b><n></tt></dt>
-  <dd>A 'bits' type is an arbitrary, but fixed, size integer that is broken up
-  into individual bits.  This type is useful because it can handle some bits
-  being defined while others are undefined.</dd>
-
-<dt><tt><b>list</b><ty></tt></dt>
-  <dd>This type represents a list whose elements are some other type.  The
-  contained type is arbitrary: it can even be another list type.</dd>
-
-<dt>Class type</dt>
-  <dd>Specifying a class name in a type context means that the defined value
-  must be a subclass of the specified class.  This is useful in conjunction with
-  the <b><tt>list</tt></b> type, for example, to constrain the elements of the
-  list to a common base class (e.g., a <tt><b>list</b><Register></tt> can
-  only contain definitions derived from the "<tt>Register</tt>" class).</dd>
-
-<dt><tt><b>dag</b></tt></dt>
-  <dd>This type represents a nestable directed graph of elements.</dd>
-
-<dt><tt><b>code</b></tt></dt>
-  <dd>This represents a big hunk of text.  This is lexically distinct from 
-  string values because it doesn't require escapeing double quotes and other
-  common characters that occur in code.</dd>
-</dl>
-
-<p>To date, these types have been sufficient for describing things that
-TableGen has been used for, but it is straight-forward to extend this list if
-needed.</p>
-
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="values">TableGen values and expressions</a>
-</h4>
-
-<div>
-
-<p>TableGen allows for a pretty reasonable number of different expression forms
-when building up values.  These forms allow the TableGen file to be written in a
-natural syntax and flavor for the application.  The current expression forms
-supported include:</p>
-
-<dl>
-<dt><tt>?</tt></dt>
-  <dd>uninitialized field</dd>
-<dt><tt>0b1001011</tt></dt>
-  <dd>binary integer value</dd>
-<dt><tt>07654321</tt></dt>
-  <dd>octal integer value (indicated by a leading 0)</dd>
-<dt><tt>7</tt></dt>
-  <dd>decimal integer value</dd>
-<dt><tt>0x7F</tt></dt>
-  <dd>hexadecimal integer value</dd>
-<dt><tt>"foo"</tt></dt>
-  <dd>string value</dd>
-<dt><tt>[{ ... }]</tt></dt>
-  <dd>code fragment</dd>
-<dt><tt>[ X, Y, Z ]<type></tt></dt>
-  <dd>list value.  <type> is the type of the list 
-element and is usually optional.  In rare cases,
-TableGen is unable to deduce the element type in
-which case the user must specify it explicitly.</dd>
-<dt><tt>{ a, b, c }</tt></dt>
-  <dd>initializer for a "bits<3>" value</dd>
-<dt><tt>value</tt></dt>
-  <dd>value reference</dd>
-<dt><tt>value{17}</tt></dt>
-  <dd>access to one bit of a value</dd>
-<dt><tt>value{15-17}</tt></dt>
-  <dd>access to multiple bits of a value</dd>
-<dt><tt>DEF</tt></dt>
-  <dd>reference to a record definition</dd>
-<dt><tt>CLASS<val list></tt></dt>
-  <dd>reference to a new anonymous definition of CLASS with the specified
-      template arguments.</dd>
-<dt><tt>X.Y</tt></dt>
-  <dd>reference to the subfield of a value</dd>
-<dt><tt>list[4-7,17,2-3]</tt></dt>
-  <dd>A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from
-  it.  Elements may be included multiple times.</dd>
-<dt><tt>foreach <var> = [ <list> ] in { <body> }</tt></dt>
-<dt><tt>foreach <var> = [ <list> ] in <def></tt></dt>
-  <dd> Replicate <body> or <def>, replacing instances of
-  <var> with each value in <list>.  <var> is scoped at the
-  level of the <tt>foreach</tt> loop and must not conflict with any other object
-  introduced in <body> or <def>.  Currently only <tt>def</tt>s are
-  expanded within <body>.
-  </dd>
-<dt><tt>foreach <var> = 0-15 in ...</tt></dt>
-<dt><tt>foreach <var> = {0-15,32-47} in ...</tt></dt>
-  <dd>Loop over ranges of integers. The braces are required for multiple
-  ranges.</dd>
-<dt><tt>(DEF a, b)</tt></dt>
-  <dd>a dag value.  The first element is required to be a record definition, the
-  remaining elements in the list may be arbitrary other values, including nested
-  `<tt>dag</tt>' values.</dd>
-<dt><tt>!strconcat(a, b)</tt></dt>
-  <dd>A string value that is the result of concatenating the 'a' and 'b'
-  strings.</dd>
-<dt><tt>str1#str2</tt></dt>
-  <dd>"#" (paste) is a shorthand for !strconcat.  It may concatenate
-  things that are not quoted strings, in which case an implicit
-  !cast<string> is done on the operand of the paste.</dd>
-<dt><tt>!cast<type>(a)</tt></dt>
-  <dd>A symbol of type <em>type</em> obtained by looking up the string 'a' in
-the symbol table.  If the type of 'a' does not match <em>type</em>, TableGen
-aborts with an error. !cast<string> is a special case in that the argument must
-be an object defined by a 'def' construct.</dd>
-<dt><tt>!subst(a, b, c)</tt></dt>
-  <dd>If 'a' and 'b' are of string type or are symbol references, substitute 
-'b' for 'a' in 'c.'  This operation is analogous to $(subst) in GNU make.</dd>
-<dt><tt>!foreach(a, b, c)</tt></dt>
-  <dd>For each member 'b' of dag or list 'a' apply operator 'c.'  'b' is a 
-dummy variable that should be declared as a member variable of an instantiated 
-class.  This operation is analogous to $(foreach) in GNU make.</dd>
-<dt><tt>!head(a)</tt></dt>
-  <dd>The first element of list 'a.'</dd>
-<dt><tt>!tail(a)</tt></dt>
-  <dd>The 2nd-N elements of list 'a.'</dd>
-<dt><tt>!empty(a)</tt></dt>
-  <dd>An integer {0,1} indicating whether list 'a' is empty.</dd>
-<dt><tt>!if(a,b,c)</tt></dt>
-  <dd>'b' if the result of 'int' or 'bit' operator 'a' is nonzero,
-      'c' otherwise.</dd>
-<dt><tt>!eq(a,b)</tt></dt>
-  <dd>'bit 1' if string a is equal to string b, 0 otherwise.  This
-      only operates on string, int and bit objects.  Use !cast<string> to
-      compare other types of objects.</dd>
-</dl>
-
-<p>Note that all of the values have rules specifying how they convert to values
-for different types.  These rules allow you to assign a value like "<tt>7</tt>"
-to a "<tt>bits<4></tt>" value, for example.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="classesdefs">Classes and definitions</a>
-</h3>
-
-<div>
-
-<p>As mentioned in the <a href="#concepts">intro</a>, classes and definitions
-(collectively known as 'records') in TableGen are the main high-level unit of
-information that TableGen collects.  Records are defined with a <tt>def</tt> or
-<tt>class</tt> keyword, the record name, and an optional list of "<a
-href="#templateargs">template arguments</a>".  If the record has superclasses,
-they are specified as a comma separated list that starts with a colon character
-("<tt>:</tt>").  If <a href="#valuedef">value definitions</a> or <a
-href="#recordlet">let expressions</a> are needed for the class, they are
-enclosed in curly braces ("<tt>{}</tt>"); otherwise, the record ends with a
-semicolon.</p>
-
-<p>Here is a simple TableGen file:</p>
-
-<div class="doc_code">
-<pre>
-<b>class</b> C { <b>bit</b> V = 1; }
-<b>def</b> X : C;
-<b>def</b> Y : C {
-  <b>string</b> Greeting = "hello";
-}
-</pre>
-</div>
-
-<p>This example defines two definitions, <tt>X</tt> and <tt>Y</tt>, both of
-which derive from the <tt>C</tt> class.  Because of this, they both get the
-<tt>V</tt> bit value.  The <tt>Y</tt> definition also gets the Greeting member
-as well.</p>
-
-<p>In general, classes are useful for collecting together the commonality
-between a group of records and isolating it in a single place.  Also, classes
-permit the specification of default values for their subclasses, allowing the
-subclasses to override them as they wish.</p>
-
-<!---------------------------------------------------------------------------->
-<h4>
-  <a name="valuedef">Value definitions</a>
-</h4>
-
-<div>
-
-<p>Value definitions define named entries in records.  A value must be defined
-before it can be referred to as the operand for another value definition or
-before the value is reset with a <a href="#recordlet">let expression</a>.  A
-value is defined by specifying a <a href="#types">TableGen type</a> and a name.
-If an initial value is available, it may be specified after the type with an
-equal sign.  Value definitions require terminating semicolons.</p>
-
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="recordlet">'let' expressions</a>
-</h4>
-
-<div>
-
-<p>A record-level let expression is used to change the value of a value
-definition in a record.  This is primarily useful when a superclass defines a
-value that a derived class or definition wants to override.  Let expressions
-consist of the '<tt>let</tt>' keyword followed by a value name, an equal sign
-("<tt>=</tt>"), and a new value.  For example, a new class could be added to the
-example above, redefining the <tt>V</tt> field for all of its subclasses:</p>
-
-<div class="doc_code">
-<pre>
-<b>class</b> D : C { let V = 0; }
-<b>def</b> Z : D;
-</pre>
-</div>
-
-<p>In this case, the <tt>Z</tt> definition will have a zero value for its "V"
-value, despite the fact that it derives (indirectly) from the <tt>C</tt> class,
-because the <tt>D</tt> class overrode its value.</p>
-
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="templateargs">Class template arguments</a>
-</h4>
-
-<div>
-
-<p>TableGen permits the definition of parameterized classes as well as normal
-concrete classes.  Parameterized TableGen classes specify a list of variable
-bindings (which may optionally have defaults) that are bound when used.  Here is
-a simple example:</p>
-
-<div class="doc_code">
-<pre>
-<b>class</b> FPFormat<<b>bits</b><3> val> {
-  <b>bits</b><3> Value = val;
-}
-<b>def</b> NotFP      : FPFormat<0>;
-<b>def</b> ZeroArgFP  : FPFormat<1>;
-<b>def</b> OneArgFP   : FPFormat<2>;
-<b>def</b> OneArgFPRW : FPFormat<3>;
-<b>def</b> TwoArgFP   : FPFormat<4>;
-<b>def</b> CompareFP  : FPFormat<5>;
-<b>def</b> CondMovFP  : FPFormat<6>;
-<b>def</b> SpecialFP  : FPFormat<7>;
-</pre>
-</div>
-
-<p>In this case, template arguments are used as a space efficient way to specify
-a list of "enumeration values", each with a "<tt>Value</tt>" field set to the
-specified integer.</p>
-
-<p>The more esoteric forms of <a href="#values">TableGen expressions</a> are
-useful in conjunction with template arguments.  As an example:</p>
-
-<div class="doc_code">
-<pre>
-<b>class</b> ModRefVal<<b>bits</b><2> val> {
-  <b>bits</b><2> Value = val;
-}
-
-<b>def</b> None   : ModRefVal<0>;
-<b>def</b> Mod    : ModRefVal<1>;
-<b>def</b> Ref    : ModRefVal<2>;
-<b>def</b> ModRef : ModRefVal<3>;
-
-<b>class</b> Value<ModRefVal MR> {
-  <i>// Decode some information into a more convenient format, while providing
-  // a nice interface to the user of the "Value" class.</i>
-  <b>bit</b> isMod = MR.Value{0};
-  <b>bit</b> isRef = MR.Value{1};
-
-  <i>// other stuff...</i>
-}
-
-<i>// Example uses</i>
-<b>def</b> bork : Value<Mod>;
-<b>def</b> zork : Value<Ref>;
-<b>def</b> hork : Value<ModRef>;
-</pre>
-</div>
-
-<p>This is obviously a contrived example, but it shows how template arguments
-can be used to decouple the interface provided to the user of the class from the
-actual internal data representation expected by the class.  In this case,
-running <tt>llvm-tblgen</tt> on the example prints the following 
-definitions:</p>
-
-<div class="doc_code">
-<pre>
-<b>def</b> bork {      <i>// Value</i>
-  <b>bit</b> isMod = 1;
-  <b>bit</b> isRef = 0;
-}
-<b>def</b> hork {      <i>// Value</i>
-  <b>bit</b> isMod = 1;
-  <b>bit</b> isRef = 1;
-}
-<b>def</b> zork {      <i>// Value</i>
-  <b>bit</b> isMod = 0;
-  <b>bit</b> isRef = 1;
-}
-</pre>
-</div>
-
-<p> This shows that TableGen was able to dig into the argument and extract a
-piece of information that was requested by the designer of the "Value" class.
-For more realistic examples, please see existing users of TableGen, such as the
-X86 backend.</p>
-
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="multiclass">Multiclass definitions and instances</a>
-</h4>
-
-<div>
-
-<p>
-While classes with template arguments are a good way to factor commonality
-between two instances of a definition, multiclasses allow a convenient notation
-for defining multiple definitions at once (instances of implicitly constructed
-classes).  For example, consider an 3-address instruction set whose instructions
-come in two forms: "<tt>reg = reg op reg</tt>" and "<tt>reg = reg op imm</tt>"
-(e.g. SPARC). In this case, you'd like to specify in one place that this
-commonality exists, then in a separate place indicate what all the ops are.
-</p>
-
-<p>
-Here is an example TableGen fragment that shows this idea:
-</p>
-
-<div class="doc_code">
-<pre>
-<b>def</b> ops;
-<b>def</b> GPR;
-<b>def</b> Imm;
-<b>class</b> inst<<b>int</b> opc, <b>string</b> asmstr, <b>dag</b> operandlist>;
-
-<b>multiclass</b> ri_inst<<b>int</b> opc, <b>string</b> asmstr> {
-  def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-                 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
-  def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-                 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
-}
-
-<i>// Instantiations of the ri_inst multiclass.</i>
-<b>defm</b> ADD : ri_inst<0b111, "add">;
-<b>defm</b> SUB : ri_inst<0b101, "sub">;
-<b>defm</b> MUL : ri_inst<0b100, "mul">;
-...
-</pre>
-</div>
-
-<p>The name of the resultant definitions has the multidef fragment names
-   appended to them, so this defines <tt>ADD_rr</tt>, <tt>ADD_ri</tt>,
-   <tt>SUB_rr</tt>, etc.  A defm may inherit from multiple multiclasses,
-   instantiating definitions from each multiclass.  Using a multiclass
-   this way is exactly equivalent to instantiating the classes multiple
-   times yourself, e.g. by writing:</p>
-
-<div class="doc_code">
-<pre>
-<b>def</b> ops;
-<b>def</b> GPR;
-<b>def</b> Imm;
-<b>class</b> inst<<b>int</b> opc, <b>string</b> asmstr, <b>dag</b> operandlist>;
-
-<b>class</b> rrinst<<b>int</b> opc, <b>string</b> asmstr>
-  : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-         (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
-
-<b>class</b> riinst<<b>int</b> opc, <b>string</b> asmstr>
-  : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-         (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
-
-<i>// Instantiations of the ri_inst multiclass.</i>
-<b>def</b> ADD_rr : rrinst<0b111, "add">;
-<b>def</b> ADD_ri : riinst<0b111, "add">;
-<b>def</b> SUB_rr : rrinst<0b101, "sub">;
-<b>def</b> SUB_ri : riinst<0b101, "sub">;
-<b>def</b> MUL_rr : rrinst<0b100, "mul">;
-<b>def</b> MUL_ri : riinst<0b100, "mul">;
-...
-</pre>
-</div>
-
-<p>
-A defm can also be used inside a multiclass providing several levels of
-multiclass instanciations.
-</p>
-
-<div class="doc_code">
-<pre>
-<b>class</b> Instruction<bits<4> opc, string Name> {
-  bits<4> opcode = opc;
-  string name = Name;
-}
-
-<b>multiclass</b> basic_r<bits<4> opc> {
-  <b>def</b> rr : Instruction<opc, "rr">;
-  <b>def</b> rm : Instruction<opc, "rm">;
-}
-
-<b>multiclass</b> basic_s<bits<4> opc> {
-  <b>defm</b> SS : basic_r<opc>;
-  <b>defm</b> SD : basic_r<opc>;
-  <b>def</b> X : Instruction<opc, "x">;
-}
-
-<b>multiclass</b> basic_p<bits<4> opc> {
-  <b>defm</b> PS : basic_r<opc>;
-  <b>defm</b> PD : basic_r<opc>;
-  <b>def</b> Y : Instruction<opc, "y">;
-}
-
-<b>defm</b> ADD : basic_s<0xf>, basic_p<0xf>;
-...
-
-<i>// Results</i>
-<b>def</b> ADDPDrm { ...
-<b>def</b> ADDPDrr { ...
-<b>def</b> ADDPSrm { ...
-<b>def</b> ADDPSrr { ...
-<b>def</b> ADDSDrm { ...
-<b>def</b> ADDSDrr { ...
-<b>def</b> ADDY { ...
-<b>def</b> ADDX { ...
-</pre>
-</div>
-
-<p>
-defm declarations can inherit from classes too, the
-rule to follow is that the class list must start after the
-last multiclass, and there must be at least one multiclass
-before them.
-</p>
-
-<div class="doc_code">
-<pre>
-<b>class</b> XD { bits<4> Prefix = 11; }
-<b>class</b> XS { bits<4> Prefix = 12; }
-
-<b>class</b> I<bits<4> op> {
-  bits<4> opcode = op;
-}
-
-<b>multiclass</b> R {
-  <b>def</b> rr : I<4>;
-  <b>def</b> rm : I<2>;
-}
-
-<b>multiclass</b> Y {
-  <b>defm</b> SS : R, XD;
-  <b>defm</b> SD : R, XS;
-}
-
-<b>defm</b> Instr : Y;
-
-<i>// Results</i>
-<b>def</b> InstrSDrm {
-  bits<4> opcode = { 0, 0, 1, 0 };
-  bits<4> Prefix = { 1, 1, 0, 0 };
-}
-...
-<b>def</b> InstrSSrr {
-  bits<4> opcode = { 0, 1, 0, 0 };
-  bits<4> Prefix = { 1, 0, 1, 1 };
-}
-</pre>
-</div>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="filescope">File scope entities</a>
-</h3>
-
-<div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="include">File inclusion</a>
-</h4>
-
-<div>
-<p>TableGen supports the '<tt>include</tt>' token, which textually substitutes
-the specified file in place of the include directive.  The filename should be
-specified as a double quoted string immediately after the '<tt>include</tt>'
-keyword.  Example:</p>
-
-<div class="doc_code">
-<pre>
-<b>include</b> "foo.td"
-</pre>
-</div>
-
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="globallet">'let' expressions</a>
-</h4>
-
-<div>
-
-<p>"Let" expressions at file scope are similar to <a href="#recordlet">"let"
-expressions within a record</a>, except they can specify a value binding for
-multiple records at a time, and may be useful in certain other cases.
-File-scope let expressions are really just another way that TableGen allows the
-end-user to factor out commonality from the records.</p>
-
-<p>File-scope "let" expressions take a comma-separated list of bindings to
-apply, and one or more records to bind the values in.  Here are some
-examples:</p>
-
-<div class="doc_code">
-<pre>
-<b>let</b> isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 <b>in</b>
-  <b>def</b> RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
-
-<b>let</b> isCall = 1 <b>in</b>
-  <i>// All calls clobber the non-callee saved registers...</i>
-  <b>let</b> Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
-              MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
-              XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] <b>in</b> {
-    <b>def</b> CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
-                           "call\t${dst:call}", []>;
-    <b>def</b> CALL32r     : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
-                        "call\t{*}$dst", [(X86call GR32:$dst)]>;
-    <b>def</b> CALL32m     : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
-                        "call\t{*}$dst", []>;
-  }
-</pre>
-</div>
-
-<p>File-scope "let" expressions are often useful when a couple of definitions
-need to be added to several records, and the records do not otherwise need to be
-opened, as in the case with the <tt>CALL*</tt> instructions above.</p>
-
-<p>It's also possible to use "let" expressions inside multiclasses, providing
-more ways to factor out commonality from the records, specially if using
-several levels of multiclass instanciations. This also avoids the need of using
-"let" expressions within subsequent records inside a multiclass.</p> 
-
-<pre class="doc_code">
-<b>multiclass </b>basic_r<bits<4> opc> {
-  <b>let </b>Predicates = [HasSSE2] in {
-    <b>def </b>rr : Instruction<opc, "rr">;
-    <b>def </b>rm : Instruction<opc, "rm">;
-  }
-  <b>let </b>Predicates = [HasSSE3] in
-    <b>def </b>rx : Instruction<opc, "rx">;
-}
-
-<b>multiclass </b>basic_ss<bits<4> opc> {
-  <b>let </b>IsDouble = 0 in
-    <b>defm </b>SS : basic_r<opc>;
-
-  <b>let </b>IsDouble = 1 in
-    <b>defm </b>SD : basic_r<opc>;
-}
-
-<b>defm </b>ADD : basic_ss<0xf>;
-</pre>
-</div>
-
-<!-- -------------------------------------------------------------------------->
-<h4>
-  <a name="foreach">Looping</a>
-</h4>
-
-<div>
-<p>TableGen supports the '<tt>foreach</tt>' block, which textually replicates
-the loop body, substituting iterator values for iterator references in the
-body.  Example:</p>
-
-<div class="doc_code">
-<pre>
-<b>foreach</b> i = [0, 1, 2, 3] in {
-  <b>def</b> R#i : Register<...>;
-  <b>def</b> F#i : Register<...>;
-}
-</pre>
-</div>
-
-<p>This will create objects <tt>R0</tt>, <tt>R1</tt>, <tt>R2</tt> and
-<tt>R3</tt>.  <tt>foreach</tt> blocks may be nested. If there is only
-one item in the body the braces may be elided:</p>
-
-<div class="doc_code">
-<pre>
-<b>foreach</b> i = [0, 1, 2, 3] in
-  <b>def</b> R#i : Register<...>;
-
-</pre>
-</div>
-
-</div>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="codegen">Code Generator backend info</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>Expressions used by code generator to describe instructions and isel
-patterns:</p>
-
-<dl>
-<dt><tt>(implicit a)</tt></dt>
-  <dd>an implicitly defined physical register.  This tells the dag instruction
-  selection emitter the input pattern's extra definitions matches implicit
-  physical register definitions.</dd>
-</dl>
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="backends">TableGen backends</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>TODO: How they work, how to write one.  This section should not contain
-details about any particular backend, except maybe -print-enums as an example.
-This should highlight the APIs in <tt>TableGen/Record.h</tt>.</p>
-
-</div>
-
-<!-- *********************************************************************** -->
-
-<hr>
-<address>
-  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
-  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
-  <a href="http://validator.w3.org/check/referer"><img
-  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
-
-  <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
-  <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
-  Last modified: $Date$
-</address>
-
-</body>
-</html>

Added: llvm/trunk/docs/TableGenFundamentals.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TableGenFundamentals.rst?rev=158903&view=auto
==============================================================================
--- llvm/trunk/docs/TableGenFundamentals.rst (added)
+++ llvm/trunk/docs/TableGenFundamentals.rst Thu Jun 21 01:58:24 2012
@@ -0,0 +1,799 @@
+.. _tablegen:
+
+=====================
+TableGen Fundamentals
+=====================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+TableGen's purpose is to help a human develop and maintain records of
+domain-specific information.  Because there may be a large number of these
+records, it is specifically designed to allow writing flexible descriptions and
+for common features of these records to be factored out.  This reduces the
+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 `TableGen backend`_ for processing.
+The current major user of TableGen is the `LLVM code
+generator <CodeGenerator.html>`_.
+
+Note that if you work on TableGen much, and use emacs or vim, that you can find
+an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
+``llvm/utils/vim`` directories of your LLVM distribution, respectively.
+
+.. _intro:
+
+Basic concepts
+--------------
+
+TableGen files consist of two key parts: 'classes' and 'definitions', both of
+which are considered 'records'.
+
+**TableGen records** have a unique name, a list of values, and a list of
+superclasses.  The list of values is the main data that TableGen builds for each
+record; it is this that holds the domain specific information for the
+application.  The interpretation of this data is left to a specific `TableGen
+backend`_, but the structure and format rules are taken care of and are fixed by
+TableGen.
+
+**TableGen definitions** are the concrete form of 'records'.  These generally do
+not have any undefined values, and are marked with the '``def``' keyword.
+
+**TableGen classes** are abstract records that are used to build and describe
+other records.  These 'classes' allow the end-user to build abstractions for
+either the domain they are targeting (such as "Register", "RegisterClass", and
+"Instruction" in the LLVM code generator) or for the implementor to help factor
+out common properties of records (such as "FPInst", which is used to represent
+floating point instructions in the X86 backend).  TableGen keeps track of all of
+the classes that are used to build up a definition, so the backend can find all
+definitions of a particular class, such as "Instruction".
+
+**TableGen multiclasses** are groups of abstract records that are instantiated
+all at once.  Each instantiation can result in multiple TableGen definitions.
+If a multiclass inherits from another multiclass, the definitions in the
+sub-multiclass become part of the current multiclass, as if they were declared
+in the current multiclass.
+
+.. _described above:
+
+An example record
+-----------------
+
+With no other arguments, TableGen parses the specified file and prints out all
+of the classes, then all of the definitions.  This is a good way to see what the
+various definitions expand to fully.  Running this on the ``X86.td`` file prints
+this (at the time of this writing):
+
+.. code-block:: llvm
+
+  ...
+  def ADD32rr {   // Instruction X86Inst I
+    string Namespace = "X86";
+    dag OutOperandList = (outs GR32:$dst);
+    dag InOperandList = (ins GR32:$src1, GR32:$src2);
+    string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
+    list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
+    list<Register> Uses = [];
+    list<Register> Defs = [EFLAGS];
+    list<Predicate> Predicates = [];
+    int CodeSize = 3;
+    int AddedComplexity = 0;
+    bit isReturn = 0;
+    bit isBranch = 0;
+    bit isIndirectBranch = 0;
+    bit isBarrier = 0;
+    bit isCall = 0;
+    bit canFoldAsLoad = 0;
+    bit mayLoad = 0;
+    bit mayStore = 0;
+    bit isImplicitDef = 0;
+    bit isConvertibleToThreeAddress = 1;
+    bit isCommutable = 1;
+    bit isTerminator = 0;
+    bit isReMaterializable = 0;
+    bit isPredicable = 0;
+    bit hasDelaySlot = 0;
+    bit usesCustomInserter = 0;
+    bit hasCtrlDep = 0;
+    bit isNotDuplicable = 0;
+    bit hasSideEffects = 0;
+    bit neverHasSideEffects = 0;
+    InstrItinClass Itinerary = NoItinerary;
+    string Constraints = "";
+    string DisableEncoding = "";
+    bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
+    Format Form = MRMDestReg;
+    bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
+    ImmType ImmT = NoImm;
+    bits<3> ImmTypeBits = { 0, 0, 0 };
+    bit hasOpSizePrefix = 0;
+    bit hasAdSizePrefix = 0;
+    bits<4> Prefix = { 0, 0, 0, 0 };
+    bit hasREX_WPrefix = 0;
+    FPFormat FPForm = ?;
+    bits<3> FPFormBits = { 0, 0, 0 };
+  }
+  ...
+
+This definition corresponds to a 32-bit register-register add instruction in the
+X86.  The string after the '``def``' string indicates the name of the
+record---"``ADD32rr``" in this case---and the comment at the end of the line
+indicates the superclasses of the definition.  The body of the record contains
+all of the data that TableGen assembled for the record, indicating that the
+instruction is part of the "X86" namespace, the pattern indicating how the the
+instruction should be emitted into the assembly file, that it is a two-address
+instruction, has a particular encoding, etc.  The contents and semantics of the
+information in the record is specific to the needs of the X86 backend, and is
+only shown as an example.
+
+As you can see, a lot of information is needed for every instruction supported
+by the code generator, and specifying it all manually would be unmaintainable,
+prone to bugs, and tiring to do in the first place.  Because we are using
+TableGen, all of the information was derived from the following definition:
+
+.. code-block:: llvm
+
+  let Defs = [EFLAGS],
+      isCommutable = 1,                  // X = ADD Y,Z --> X = ADD Z,Y
+      isConvertibleToThreeAddress = 1 in // Can transform into LEA.
+  def ADD32rr  : I<0x01, MRMDestReg, (outs GR32:$dst),
+                                     (ins GR32:$src1, GR32:$src2),
+                   "add{l}\t{$src2, $dst|$dst, $src2}",
+                   [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
+
+This definition makes use of the custom class ``I`` (extended from the custom
+class ``X86Inst``), which is defined in the X86-specific TableGen file, to
+factor out the common features that instructions of its class share.  A key
+feature of TableGen is that it allows the end-user to define the abstractions
+they prefer to use when describing their information.
+
+Each def record has a special entry called "``NAME``."  This is the name of the
+def ("``ADD32rr``" above).  In the general case def names can be formed from
+various kinds of string processing expressions and ``NAME`` resolves to the
+final value obtained after resolving all of those expressions.  The user may
+refer to ``NAME`` anywhere she desires to use the ultimate name of the def.
+``NAME`` should not be defined anywhere else in user code to avoid conflict
+problems.
+
+Running TableGen
+----------------
+
+TableGen runs just like any other LLVM tool.  The first (optional) argument
+specifies the file to read.  If a filename is not specified, ``llvm-tblgen``
+reads from standard input.
+
+To be useful, one of the `TableGen backends`_ must be used.  These backends are
+selectable on the command line (type '``llvm-tblgen -help``' for a list).  For
+example, to get a list of all of the definitions that subclass a particular type
+(which can be useful for building up an enum list of these records), use the
+``-print-enums`` option:
+
+.. code-block:: bash
+
+  $ llvm-tblgen X86.td -print-enums -class=Register
+  AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
+  ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
+  MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
+  R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
+  R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
+  RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
+  XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
+  XMM6, XMM7, XMM8, XMM9,
+
+  $ llvm-tblgen X86.td -print-enums -class=Instruction 
+  ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
+  ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
+  ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
+  ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
+  ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
+
+The default backend prints out all of the records, as `described above`_.
+
+If you plan to use TableGen, you will most likely have to `write a backend`_
+that extracts the information specific to what you need and formats it in the
+appropriate way.
+
+.. _parses a file:
+
+TableGen syntax
+===============
+
+TableGen doesn't care about the meaning of data (that is up to the backend to
+define), but it does care about syntax, and it enforces a simple type system.
+This section describes the syntax and the constructs allowed in a TableGen file.
+
+TableGen primitives
+-------------------
+
+TableGen comments
+^^^^^^^^^^^^^^^^^
+
+TableGen supports BCPL style "``//``" comments, which run to the end of the
+line, and it also supports **nestable** "``/* */``" comments.
+
+.. _TableGen type:
+
+The TableGen type system
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+TableGen files are strongly typed, in a simple (but complete) type-system.
+These types are used to perform automatic conversions, check for errors, and to
+help interface designers constrain the input that they allow.  Every `value
+definition`_ is required to have an associated type.
+
+TableGen supports a mixture of very low-level types (such as ``bit``) and very
+high-level types (such as ``dag``).  This flexibility is what allows it to
+describe a wide range of information conveniently and compactly.  The TableGen
+types are:
+
+``bit``
+    A 'bit' is a boolean value that can hold either 0 or 1.
+
+``int``
+    The 'int' type represents a simple 32-bit integer value, such as 5.
+
+``string``
+    The 'string' type represents an ordered sequence of characters of arbitrary
+    length.
+
+``bits<n>``
+    A 'bits' type is an arbitrary, but fixed, size integer that is broken up
+    into individual bits.  This type is useful because it can handle some bits
+    being defined while others are undefined.
+
+``list<ty>``
+    This type represents a list whose elements are some other type.  The
+    contained type is arbitrary: it can even be another list type.
+
+Class type
+    Specifying a class name in a type context means that the defined value must
+    be a subclass of the specified class.  This is useful in conjunction with
+    the **``list``** type, for example, to constrain the elements of the list to
+    a common base class (e.g., a ``**list**<Register>`` can only contain
+    definitions derived from the "``Register``" class).
+
+``dag``
+    This type represents a nestable directed graph of elements.
+
+``code``
+    This represents a big hunk of text.  This is lexically distinct from string
+    values because it doesn't require escaping double quotes and other common
+    characters that occur in code.
+
+To date, these types have been sufficient for describing things that TableGen
+has been used for, but it is straight-forward to extend this list if needed.
+
+.. _TableGen expressions:
+
+TableGen values and expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TableGen allows for a pretty reasonable number of different expression forms
+when building up values.  These forms allow the TableGen file to be written in a
+natural syntax and flavor for the application.  The current expression forms
+supported include:
+
+``?``
+    uninitialized field
+
+``0b1001011``
+    binary integer value
+
+``07654321``
+    octal integer value (indicated by a leading 0)
+
+``7``
+    decimal integer value
+
+``0x7F``
+    hexadecimal integer value
+
+``"foo"``
+    string value
+
+``[{ ... }]``
+    code fragment
+
+``[ X, Y, Z ]<type>``
+    list value.  <type> is the type of the list element and is usually optional.
+    In rare cases, TableGen is unable to deduce the element type in which case
+    the user must specify it explicitly.
+
+``{ a, b, c }``
+    initializer for a "bits<3>" value
+
+``value``
+    value reference
+
+``value{17}``
+    access to one bit of a value
+
+``value{15-17}``
+    access to multiple bits of a value
+
+``DEF``
+    reference to a record definition
+
+``CLASS<val list>``
+    reference to a new anonymous definition of CLASS with the specified template
+    arguments.
+
+``X.Y``
+    reference to the subfield of a value
+
+``list[4-7,17,2-3]``
+    A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
+    Elements may be included multiple times.
+
+``foreach <var> = [ <list> ] in { <body> }``
+
+``foreach <var> = [ <list> ] in <def>``
+    Replicate <body> or <def>, replacing instances of <var> with each value
+    in <list>.  <var> is scoped at the level of the ``foreach`` loop and must
+    not conflict with any other object introduced in <body> or <def>.  Currently
+    only ``def``\s are expanded within <body>.
+
+``foreach <var> = 0-15 in ...``
+
+``foreach <var> = {0-15,32-47} in ...``
+    Loop over ranges of integers. The braces are required for multiple ranges.
+
+``(DEF a, b)``
+    a dag value.  The first element is required to be a record definition, the
+    remaining elements in the list may be arbitrary other values, including
+    nested ```dag``' values.
+
+``!strconcat(a, b)``
+    A string value that is the result of concatenating the 'a' and 'b' strings.
+
+``str1#str2``
+    "#" (paste) is a shorthand for !strconcat.  It may concatenate things that
+    are not quoted strings, in which case an implicit !cast<string> is done on
+    the operand of the paste.</dd>
+
+``!cast<type>(a)``
+    A symbol of type *type* obtained by looking up the string 'a' in the symbol
+    table.  If the type of 'a' does not match *type*, TableGen aborts with an
+    error. !cast<string> is a special case in that the argument must be an
+    object defined by a 'def' construct.</dd>
+
+``!subst(a, b, c)``
+    If 'a' and 'b' are of string type or are symbol references, substitute 'b'
+    for 'a' in 'c.'  This operation is analogous to $(subst) in GNU make.
+
+``!foreach(a, b, c)``
+    For each member 'b' of dag or list 'a' apply operator 'c.'  'b' is a dummy
+    variable that should be declared as a member variable of an instantiated
+    class.  This operation is analogous to $(foreach) in GNU make.
+
+``!head(a)``
+    The first element of list 'a.'
+
+``!tail(a)``
+    The 2nd-N elements of list 'a.'
+
+``!empty(a)``
+    An integer {0,1} indicating whether list 'a' is empty.
+
+``!if(a,b,c)``
+  'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
+
+``!eq(a,b)``
+    'bit 1' if string a is equal to string b, 0 otherwise.  This only operates
+    on string, int and bit objects.  Use !cast<string> to compare other types of
+    objects.
+
+Note that all of the values have rules specifying how they convert to values
+for different types.  These rules allow you to assign a value like "``7``"
+to a "``bits<4>``" value, for example.
+
+Classes and definitions
+-----------------------
+
+As mentioned in the `intro`_, classes and definitions (collectively known as
+'records') in TableGen are the main high-level unit of information that TableGen
+collects.  Records are defined with a ``def`` or ``class`` keyword, the record
+name, and an optional list of "`template arguments`_".  If the record has
+superclasses, they are specified as a comma separated list that starts with a
+colon character ("``:``").  If `value definitions`_ or `let expressions`_ are
+needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
+the record ends with a semicolon.
+
+Here is a simple TableGen file:
+
+.. code-block:: llvm
+
+  class C { bit V = 1; }
+  def X : C;
+  def Y : C {
+    string Greeting = "hello";
+  }
+
+This example defines two definitions, ``X`` and ``Y``, both of which derive from
+the ``C`` class.  Because of this, they both get the ``V`` bit value.  The ``Y``
+definition also gets the Greeting member as well.
+
+In general, classes are useful for collecting together the commonality between a
+group of records and isolating it in a single place.  Also, classes permit the
+specification of default values for their subclasses, allowing the subclasses to
+override them as they wish.
+
+.. _value definition:
+.. _value definitions:
+
+Value definitions
+^^^^^^^^^^^^^^^^^
+
+Value definitions define named entries in records.  A value must be defined
+before it can be referred to as the operand for another value definition or
+before the value is reset with a `let expression`_.  A value is defined by
+specifying a `TableGen type`_ and a name.  If an initial value is available, it
+may be specified after the type with an equal sign.  Value definitions require
+terminating semicolons.
+
+.. _let expression:
+.. _let expressions:
+.. _"let" expressions within a record:
+
+'let' expressions
+^^^^^^^^^^^^^^^^^
+
+A record-level let expression is used to change the value of a value definition
+in a record.  This is primarily useful when a superclass defines a value that a
+derived class or definition wants to override.  Let expressions consist of the
+'``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
+value.  For example, a new class could be added to the example above, redefining
+the ``V`` field for all of its subclasses:
+
+.. code-block:: llvm
+
+  class D : C { let V = 0; }
+  def Z : D;
+
+In this case, the ``Z`` definition will have a zero value for its ``V`` value,
+despite the fact that it derives (indirectly) from the ``C`` class, because the
+``D`` class overrode its value.
+
+.. _template arguments:
+
+Class template arguments
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+TableGen permits the definition of parameterized classes as well as normal
+concrete classes.  Parameterized TableGen classes specify a list of variable
+bindings (which may optionally have defaults) that are bound when used.  Here is
+a simple example:
+
+.. code-block:: llvm
+
+  class FPFormat<bits<3> val> {
+    bits<3> Value = val;
+  }
+  def NotFP      : FPFormat<0>;
+  def ZeroArgFP  : FPFormat<1>;
+  def OneArgFP   : FPFormat<2>;
+  def OneArgFPRW : FPFormat<3>;
+  def TwoArgFP   : FPFormat<4>;
+  def CompareFP  : FPFormat<5>;
+  def CondMovFP  : FPFormat<6>;
+  def SpecialFP  : FPFormat<7>;
+
+In this case, template arguments are used as a space efficient way to specify a
+list of "enumeration values", each with a "``Value``" field set to the specified
+integer.
+
+The more esoteric forms of `TableGen expressions`_ are useful in conjunction
+with template arguments.  As an example:
+
+.. code-block:: llvm
+
+  class ModRefVal<bits<2> val> {
+    bits<2> Value = val;
+  }
+
+  def None   : ModRefVal<0>;
+  def Mod    : ModRefVal<1>;
+  def Ref    : ModRefVal<2>;
+  def ModRef : ModRefVal<3>;
+
+  class Value<ModRefVal MR> {
+    // Decode some information into a more convenient format, while providing
+    // a nice interface to the user of the "Value" class.
+    bit isMod = MR.Value{0};
+    bit isRef = MR.Value{1};
+
+    // other stuff...
+  }
+
+  // Example uses
+  def bork : Value<Mod>;
+  def zork : Value<Ref>;
+  def hork : Value<ModRef>;
+
+This is obviously a contrived example, but it shows how template arguments can
+be used to decouple the interface provided to the user of the class from the
+actual internal data representation expected by the class.  In this case,
+running ``llvm-tblgen`` on the example prints the following definitions:
+
+.. code-block:: llvm
+
+  def bork {      // Value
+    bit isMod = 1;
+    bit isRef = 0;
+  }
+  def hork {      // Value
+    bit isMod = 1;
+    bit isRef = 1;
+  }
+  def zork {      // Value
+    bit isMod = 0;
+    bit isRef = 1;
+  }
+
+This shows that TableGen was able to dig into the argument and extract a piece
+of information that was requested by the designer of the "Value" class.  For
+more realistic examples, please see existing users of TableGen, such as the X86
+backend.
+
+Multiclass definitions and instances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While classes with template arguments are a good way to factor commonality
+between two instances of a definition, multiclasses allow a convenient notation
+for defining multiple definitions at once (instances of implicitly constructed
+classes).  For example, consider an 3-address instruction set whose instructions
+come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
+(e.g. SPARC). In this case, you'd like to specify in one place that this
+commonality exists, then in a separate place indicate what all the ops are.
+
+Here is an example TableGen fragment that shows this idea:
+
+.. code-block:: llvm
+
+  def ops;
+  def GPR;
+  def Imm;
+  class inst<int opc, string asmstr, dag operandlist>;
+
+  multiclass ri_inst<int opc, string asmstr> {
+    def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+                   (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+    def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+                   (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+  }
+
+  // Instantiations of the ri_inst multiclass.
+  defm ADD : ri_inst<0b111, "add">;
+  defm SUB : ri_inst<0b101, "sub">;
+  defm MUL : ri_inst<0b100, "mul">;
+  ...
+
+The name of the resultant definitions has the multidef fragment names appended
+to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc.  A defm may
+inherit from multiple multiclasses, instantiating definitions from each
+multiclass.  Using a multiclass this way is exactly equivalent to instantiating
+the classes multiple times yourself, e.g. by writing:
+
+.. code-block:: llvm
+
+  def ops;
+  def GPR;
+  def Imm;
+  class inst<int opc, string asmstr, dag operandlist>;
+
+  class rrinst<int opc, string asmstr>
+    : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+           (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+
+  class riinst<int opc, string asmstr>
+    : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+           (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+
+  // Instantiations of the ri_inst multiclass.
+  def ADD_rr : rrinst<0b111, "add">;
+  def ADD_ri : riinst<0b111, "add">;
+  def SUB_rr : rrinst<0b101, "sub">;
+  def SUB_ri : riinst<0b101, "sub">;
+  def MUL_rr : rrinst<0b100, "mul">;
+  def MUL_ri : riinst<0b100, "mul">;
+  ...
+
+A ``defm`` can also be used inside a multiclass providing several levels of
+multiclass instanciations.
+
+.. code-block:: llvm
+
+  class Instruction<bits<4> opc, string Name> {
+    bits<4> opcode = opc;
+    string name = Name;
+  }
+
+  multiclass basic_r<bits<4> opc> {
+    def rr : Instruction<opc, "rr">;
+    def rm : Instruction<opc, "rm">;
+  }
+
+  multiclass basic_s<bits<4> opc> {
+    defm SS : basic_r<opc>;
+    defm SD : basic_r<opc>;
+    def X : Instruction<opc, "x">;
+  }
+
+  multiclass basic_p<bits<4> opc> {
+    defm PS : basic_r<opc>;
+    defm PD : basic_r<opc>;
+    def Y : Instruction<opc, "y">;
+  }
+
+  defm ADD : basic_s<0xf>, basic_p<0xf>;
+  ...
+
+  // Results
+  def ADDPDrm { ...
+  def ADDPDrr { ...
+  def ADDPSrm { ...
+  def ADDPSrr { ...
+  def ADDSDrm { ...
+  def ADDSDrr { ...
+  def ADDY { ...
+  def ADDX { ...
+
+``defm`` declarations can inherit from classes too, the rule to follow is that
+the class list must start after the last multiclass, and there must be at least
+one multiclass before them.
+
+.. code-block:: llvm
+
+  class XD { bits<4> Prefix = 11; }
+  class XS { bits<4> Prefix = 12; }
+
+  class I<bits<4> op> {
+    bits<4> opcode = op;
+  }
+
+  multiclass R {
+    def rr : I<4>;
+    def rm : I<2>;
+  }
+
+  multiclass Y {
+    defm SS : R, XD;
+    defm SD : R, XS;
+  }
+
+  defm Instr : Y;
+
+  // Results
+  def InstrSDrm {
+    bits<4> opcode = { 0, 0, 1, 0 };
+    bits<4> Prefix = { 1, 1, 0, 0 };
+  }
+  ...
+  def InstrSSrr {
+    bits<4> opcode = { 0, 1, 0, 0 };
+    bits<4> Prefix = { 1, 0, 1, 1 };
+  }
+
+File scope entities
+-------------------
+
+File inclusion
+^^^^^^^^^^^^^^
+
+TableGen supports the '``include``' token, which textually substitutes the
+specified file in place of the include directive.  The filename should be
+specified as a double quoted string immediately after the '``include``' keyword.
+Example:
+
+.. code-block:: llvm
+
+  include "foo.td"
+
+'let' expressions
+^^^^^^^^^^^^^^^^^
+
+"Let" expressions at file scope are similar to `"let" expressions within a
+record`_, except they can specify a value binding for multiple records at a
+time, and may be useful in certain other cases.  File-scope let expressions are
+really just another way that TableGen allows the end-user to factor out
+commonality from the records.
+
+File-scope "let" expressions take a comma-separated list of bindings to apply,
+and one or more records to bind the values in.  Here are some examples:
+
+.. code-block:: llvm
+
+  let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
+    def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
+
+  let isCall = 1 in
+    // All calls clobber the non-callee saved registers...
+    let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
+                MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
+                XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
+      def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
+                             "call\t${dst:call}", []>;
+      def CALL32r     : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
+                          "call\t{*}$dst", [(X86call GR32:$dst)]>;
+      def CALL32m     : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
+                          "call\t{*}$dst", []>;
+    }
+
+File-scope "let" expressions are often useful when a couple of definitions need
+to be added to several records, and the records do not otherwise need to be
+opened, as in the case with the ``CALL*`` instructions above.
+
+It's also possible to use "let" expressions inside multiclasses, providing more
+ways to factor out commonality from the records, specially if using several
+levels of multiclass instanciations. This also avoids the need of using "let"
+expressions within subsequent records inside a multiclass.
+
+.. code-block:: llvm
+
+  multiclass basic_r<bits<4> opc> {
+    let Predicates = [HasSSE2] in {
+      def rr : Instruction<opc, "rr">;
+      def rm : Instruction<opc, "rm">;
+    }
+    let Predicates = [HasSSE3] in
+      def rx : Instruction<opc, "rx">;
+  }
+
+  multiclass basic_ss<bits<4> opc> {
+    let IsDouble = 0 in
+      defm SS : basic_r<opc>;
+
+    let IsDouble = 1 in
+      defm SD : basic_r<opc>;
+  }
+
+  defm ADD : basic_ss<0xf>;
+
+Looping
+^^^^^^^
+
+TableGen supports the '``foreach``' block, which textually replicates the loop
+body, substituting iterator values for iterator references in the body.
+Example:
+
+.. code-block:: llvm
+
+  foreach i = [0, 1, 2, 3] in {
+    def R#i : Register<...>;
+    def F#i : Register<...>;
+  }
+
+This will create objects ``R0``, ``R1``, ``R2`` and ``R3``.  ``foreach`` blocks
+may be nested. If there is only one item in the body the braces may be
+elided:
+
+.. code-block:: llvm
+
+  foreach i = [0, 1, 2, 3] in
+    def R#i : Register<...>;
+
+Code Generator backend info
+===========================
+
+Expressions used by code generator to describe instructions and isel patterns:
+
+``(implicit a)``
+    an implicitly defined physical register.  This tells the dag instruction
+    selection emitter the input pattern's extra definitions matches implicit
+    physical register definitions.
+
+.. _TableGen backend:
+.. _TableGen backends:
+.. _write a backend:
+
+TableGen backends
+=================
+
+TODO: How they work, how to write one.  This section should not contain details
+about any particular backend, except maybe ``-print-enums`` as an example.  This
+should highlight the APIs in ``TableGen/Record.h``.

Modified: llvm/trunk/docs/subsystems.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/subsystems.rst?rev=158903&r1=158902&r2=158903&view=diff
==============================================================================
--- llvm/trunk/docs/subsystems.rst (original)
+++ llvm/trunk/docs/subsystems.rst Thu Jun 21 01:58:24 2012
@@ -10,6 +10,7 @@
    BranchWeightMetadata
    LinkTimeOptimization
    SegmentedStacks
+   TableGenFundamentals
 
 * `Writing an LLVM Pass <WritingAnLLVMPass.html>`_
     
@@ -25,8 +26,8 @@
    working on retargetting LLVM to a new architecture, designing a new codegen
    pass, or enhancing existing components.
     
-* `TableGen Fundamentals <TableGenFundamentals.html>`_
-    
+* :ref:`tablegen`
+
    Describes the TableGen tool, which is used heavily by the LLVM code
    generator.
     





More information about the llvm-commits mailing list