"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="llvm.css" type="text/css">
+ <link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
-<div class="doc_title">TableGen Fundamentals</div>
+<h1>TableGen Fundamentals</h1>
-<div class="doc_text">
+<div>
<ul>
<li><a href="#introduction">Introduction</a>
<ol>
<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>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="introduction">Introduction</a></div>
+<h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<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
<tt>llvm/utils/emacs</tt> and <tt>llvm/utils/vim</tt> directories of your LLVM
distribution, respectively.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="concepts">Basic concepts</a></div>
+<h3><a name="concepts">Basic concepts</a></h3>
-<div class="doc_text">
+<div>
<p>TableGen files consist of two key parts: 'classes' and 'definitions', both
of which are considered 'records'.</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="example">An example record</a></div>
+<h3><a name="example">An example record</a></h3>
-<div class="doc_text">
+<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
<b>bit</b> mayLoad = 0;
<b>bit</b> mayStore = 0;
<b>bit</b> isImplicitDef = 0;
- <b>bit</b> isTwoAddress = 1;
<b>bit</b> isConvertibleToThreeAddress = 1;
<b>bit</b> isCommutable = 1;
<b>bit</b> isTerminator = 0;
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>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="running">Running TableGen</a></div>
+<h3><a name="running">Running TableGen</a></h3>
-<div class="doc_text">
+<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>tblgen</tt>
</div>
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="syntax">TableGen syntax</a></div>
+<h2><a name="syntax">TableGen syntax</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<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>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="primitives">TableGen primitives</a></div>
+<h3><a name="primitives">TableGen primitives</a></h3>
+
+<div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection"><a name="comments">TableGen comments</a></div>
+<h4><a name="comments">TableGen comments</a></h4>
-<div class="doc_text">
+<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>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="types">The TableGen type system</a>
-</div>
+</h4>
-<div class="doc_text">
+<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
</div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="values">TableGen values and expressions</a>
-</div>
+</h4>
-<div class="doc_text">
+<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
<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>(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
<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>!nameconcat<type>(a, b)</tt></dt>
- <dd>Shorthand for !cast<type>(!strconcat(a, b))</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>
<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>!car(a)</tt></dt>
+<dt><tt>!head(a)</tt></dt>
<dd>The first element of list 'a.'</dd>
-<dt><tt>!cdr(a)</tt></dt>
+<dt><tt>!tail(a)</tt></dt>
<dd>The 2nd-N elements of list 'a.'</dd>
-<dt><tt>!null(a)</tt></dt>
+<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>Integer one if string a is equal to string b, zero otherwise. This
- only operates on string, int and bit objects. Use !cast<string> to
+ <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>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="classesdefs">Classes and definitions</a>
-</div>
+</h3>
-<div class="doc_text">
+<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
permit the specification of default values for their subclasses, allowing the
subclasses to override them as they wish.</p>
-</div>
-
<!---------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="valuedef">Value definitions</a>
-</div>
+</h4>
-<div class="doc_text">
+<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
</div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="recordlet">'let' expressions</a>
-</div>
+</h4>
-<div class="doc_text">
+<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
</div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="templateargs">Class template arguments</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>TableGen permits the definition of parameterized classes as well as normal
concrete classes. Parameterized TableGen classes specify a list of variable
</div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="multiclass">Multiclass definitions and instances</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>
While classes with template arguments are a good way to factor commonality
</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>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="filescope">File scope entities</a>
-</div>
+</h3>
+
+<div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="include">File inclusion</a>
-</div>
+</h4>
-<div class="doc_text">
+<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>'
</div>
<!-- -------------------------------------------------------------------------->
-<div class="doc_subsubsection">
+<h4>
<a name="globallet">'let' expressions</a>
-</div>
+</h4>
-<div class="doc_text">
+<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
several levels of multiclass instanciations. This also avoids the need of using
"let" expressions within subsequent records inside a multiclass.</p>
-<div class="doc_code">
-<pre>
+<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">;
</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>
+
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="codegen">Code Generator backend info</a></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>
-<div class="doc_text">
-
+<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>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="backends">TableGen backends</a></div>
+<h2><a name="backends">TableGen backends</a></h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<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.
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
- <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>