1 ===========================
2 TableGen Language Reference
3 ===========================
5 .. sectionauthor:: Sean Silva <silvas@purdue.edu>
11 This document is extremely rough. If you find something lacking, please
12 fix it, file a documentation bug, or ask about it on llvmdev.
17 This document is meant to be a normative spec about the TableGen language
18 in and of itself (i.e. how to understand a given construct in terms of how
19 it affects the final set of records represented by the TableGen file). If
20 you are unsure if this document is really what you are looking for, please
21 read :doc:`/TableGenFundamentals` first.
26 The lexical and syntax notation used here is intended to imitate
27 `Python's`_. In particular, for lexical definitions, the productions
28 operate at the character level and there is no implied whitespace between
29 elements. The syntax definitions operate at the token level, so there is
30 implied whitespace between tokens.
32 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
37 TableGen supports BCPL (``// ...``) and nestable C-style (``/* ... */``)
40 The following is a listing of the basic punctuation tokens::
42 - + [ ] { } ( ) < > : ; . = ? #
44 Numeric literals take one of the following forms:
46 .. TableGen actually will lex some pretty strange sequences an interpret
47 them as numbers. What is shown here is an attempt to approximate what it
51 TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
52 DecimalInteger: ["+" | "-"] ("0"..."9")+
53 HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
54 BinInteger: "0b" ("0" | "1")+
56 One aspect to note is that the :token:`DecimalInteger` token *includes* the
57 ``+`` or ``-``, as opposed to having ``+`` and ``-`` be unary operators as
60 TableGen has identifier-like tokens:
63 ualpha: "a"..."z" | "A"..."Z" | "_"
64 TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
65 TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*
67 Note that unlike most languages, TableGen allows :token:`TokIdentifier` to
68 begin with a number. In case of ambiguity, a token will be interpreted as a
69 numeric literal rather than an identifier.
71 TableGen also has two string-like literals:
74 TokString: '"' <non-'"' characters and C-like escapes> '"'
75 TokCodeFragment: "[{" <shortest text not containing "}]"> "}]"
77 :token:`TokCodeFragment` is essentially a multiline string literal
78 delimited by ``[{`` and ``}]``.
81 The current implementation accepts the following C-like escapes::
85 TableGen also has the following keywords::
87 bit bits class code dag
88 def foreach defm field in
89 int let list multiclass string
91 TableGen also has "bang operators" which have a
92 wide variety of meanings:
96 :!eq !if !head !tail !con
98 :!cast !empty !subst !foreach !strconcat
103 TableGen has an ``include`` mechanism. It does not play a role in the
104 syntax per se, since it is lexically replaced with the contents of the
108 IncludeDirective: "include" `TokString`
110 TableGen's top-level production consists of "objects".
113 TableGenFile: `Object`*
114 Object: `Class` | `Def` | `Defm` | `Let` | `MultiClass` | `Foreach`
120 Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
122 A ``class`` declaration creates a record which other records can inherit
123 from. A class can be parametrized by a list of "template arguments", whose
124 values can be used in the class body.
126 A given class can only be defined once. A ``class`` declaration is
127 considered to define the class if any of the following is true:
129 .. break ObjectBody into its consituents so that they are present here?
131 #. The :token:`TemplateArgList` is present.
132 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
133 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
135 You can declare an empty class by giving and empty :token:`TemplateArgList`
136 and an empty :token:`ObjectBody`. This can serve as a restricted form of
137 forward declaration: note that records deriving from the forward-declared
138 class will inherit no fields from it since the record expansion is done
139 when the record is parsed.
142 TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
147 .. Omitting mention of arcane "field" prefix to discourage its use.
149 The declaration syntax is pretty much what you would expect as a C++
153 Declaration: `Type` `TokIdentifier` ["=" `Value`]
155 It assigns the value to the identifer.
161 Type: "string" | "code" | "bit" | "int" | "dag"
162 :| "bits" "<" `TokInteger` ">"
163 :| "list" "<" `Type` ">"
165 ClassID: `TokIdentifier`
167 Both ``string`` and ``code`` correspond to the string type; the difference
168 is purely to indicate programmer intention.
170 The :token:`ClassID` must identify a class that has been previously
177 Value: `SimpleValue` `ValueSuffix`*
178 ValueSuffix: "{" `RangeList` "}"
179 :| "[" `RangeList` "]"
180 :| "." `TokIdentifier`
181 RangeList: `RangePiece` ("," `RangePiece`)*
182 RangePiece: `TokInteger`
183 :| `TokInteger` "-" `TokInteger`
184 :| `TokInteger` `TokInteger`
186 The peculiar last form of :token:`RangePiece` is due to the fact that the
187 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
188 two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,
189 instead of "1", "-", and "5".
190 The :token:`RangeList` can be thought of as specifying "list slice" in some
194 :token:`SimpleValue` has a number of forms:
198 SimpleValue: `TokIdentifier`
200 The value will be the variable referenced by the identifier. It can be one
203 .. The code for this is exceptionally abstruse. These examples are a
206 * name of a ``def``, such as the use of ``Bar`` in::
208 def Bar : SomeClass {
216 * value local to a ``def``, such as the use of ``Bar`` in::
223 * a template arg of a ``class``, such as the use of ``Bar`` in::
229 * value local to a ``multiclass``, such as the use of ``Bar`` in::
236 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
238 multiclass Foo<int Bar> {
243 SimpleValue: `TokInteger`
245 This represents the numeric value of the integer.
248 SimpleValue: `TokString`+
250 Multiple adjacent string literals are concatenated like in C/C++. The value
251 is the concatenation of the strings.
254 SimpleValue: `TokCodeFragment`
256 The value is the string value of the code fragment.
261 ``?`` represents an "unset" initializer.
264 SimpleValue: "{" `ValueList` "}"
265 ValueList: [`ValueListNE`]
266 ValueListNE: `Value` ("," `Value`)*
268 This represents a sequence of bits, as would be used to initialize a
269 ``bits<n>`` field (where ``n`` is the number of bits).
272 SimpleValue: `ClassID` "<" `ValueListNE` ">"
274 This generates a new anonymous record definition (as would be created by an
275 unnamed ``def`` inheriting from the given class with the given template
276 arguments) and the value is the value of that record definition.
279 SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]
281 A list initializer. The optional :token:`Type` can be used to indicate a
282 specific element type, otherwise the element type will be deduced from the
285 .. The initial `DagArg` of the dag must start with an identifier or
286 !cast, but this is more of an implementation detail and so for now just
290 SimpleValue: "(" `DagArg` `DagArgList` ")"
291 DagArgList: `DagArg` ("," `DagArg`)*
292 DagArg: `Value` [":" `TokVarName`] | `TokVarName`
294 The initial :token:`DagArg` is called the "operator" of the dag.
297 SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
303 ObjectBody: `BaseClassList` `Body`
304 BaseClassList: [":" `BaseClassListNE`]
305 BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*
306 SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]
307 DefmID: `TokIdentifier`
309 The version with the :token:`MultiClassID` is only valid in the
310 :token:`BaseClassList` of a ``defm``.
311 The :token:`MultiClassID` should be the name of a ``multiclass``.
313 .. put this somewhere else
315 It is after parsing the base class list that the "let stack" is applied.
318 Body: ";" | "{" BodyList "}"
320 BodyItem: `Declaration` ";"
321 :| "let" `TokIdentifier` [`RangeList`] "=" `Value` ";"
323 The ``let`` form allows overriding the value of an inherited field.
329 There can be pastes in the names here, like ``#NAME#``. Look into that
330 and document it (it boils down to ParseIDValue with IDParseMode ==
331 ParseNameMode). ParseObjectName calls into the general ParseValue, with
332 the only different from "arbitrary expression parsing" being IDParseMode
336 Def: "def" `TokIdentifier` `ObjectBody`
338 Defines a record whose name is given by the :token:`TokIdentifier`. The
339 fields of the record are inherited from the base classes and defined in the
342 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
349 Defm: "defm" `TokIdentifier` ":" `BaseClassListNE` ";"
351 Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must
352 precede any ``class``'s that appear.
358 Foreach: "foreach" `Declaration` "in" "{" `Object`* "}"
359 :| "foreach" `Declaration` "in" `Object`
361 The value assigned to the variable in the declaration is iterated over and
362 the object or object list is reevaluated with the variable set at each
369 Let: "let" `LetList` "in" "{" `Object`* "}"
370 :| "let" `LetList` "in" `Object`
371 LetList: `LetItem` ("," `LetItem`)*
372 LetItem: `TokIdentifier` [`RangeList`] "=" `Value`
374 This is effectively equivalent to ``let`` inside the body of a record
375 except that it applies to multiple records at a time. The bindings are
376 applied at the end of parsing the base classes of a record.
382 MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
383 : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"
384 BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*
385 MultiClassID: `TokIdentifier`
386 MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`