"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;
<b>bit</b> isReMaterializable = 0;
<b>bit</b> isPredicable = 0;
<b>bit</b> hasDelaySlot = 0;
- <b>bit</b> usesCustomDAGSchedInserter = 0;
+ <b>bit</b> usesCustomInserter = 0;
<b>bit</b> hasCtrlDep = 0;
<b>bit</b> isNotDuplicable = 0;
<b>bit</b> hasSideEffects = 0;
- <b>bit</b> mayHaveSideEffects = 0;
<b>bit</b> neverHasSideEffects = 0;
InstrItinClass Itinerary = NoItinerary;
<b>string</b> Constraints = "";
<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
-unmaintainble, prone to bugs, and tiring to do in the first place. Because we
+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>
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
<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. NOTE: I don't remember why this is
- distinct from string!</dd>
+ <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
</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
<dd>string value</dd>
<dt><tt>[{ ... }]</tt></dt>
<dd>code fragment</dd>
-<dt><tt>[ X, Y, Z ]</tt></dt>
- <dd>list value.</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>
<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>!cast<type>(a)</tt></dt>
+<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. </dd>
-<dt><tt>!nameconcat<type>(a, b)</tt></dt>
- <dd>Shorthand for !cast<type>(!strconcat(a, b))</dd>
+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
</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>
+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>
<!-- ======================================================================= -->
-<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
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>
<!-- *********************************************************************** -->
-<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>
projects / oota-llvm.git / blobdiff