1 ===========================
2 TableGen Language Reference
3 ===========================
9 This document is extremely rough. If you find something lacking, please
10 fix it, file a documentation bug, or ask about it on llvmdev.
15 This document is meant to be a normative spec about the TableGen language
16 in and of itself (i.e. how to understand a given construct in terms of how
17 it affects the final set of records represented by the TableGen file). If
18 you are unsure if this document is really what you are looking for, please
19 read the :doc:`introduction to TableGen <index>` first.
24 The lexical and syntax notation used here is intended to imitate
25 `Python's`_. In particular, for lexical definitions, the productions
26 operate at the character level and there is no implied whitespace between
27 elements. The syntax definitions operate at the token level, so there is
28 implied whitespace between tokens.
30 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
35 TableGen supports BCPL (``// ...``) and nestable C-style (``/* ... */``)
38 The following is a listing of the basic punctuation tokens::
40 - + [ ] { } ( ) < > : ; . = ? #
42 Numeric literals take one of the following forms:
44 .. TableGen actually will lex some pretty strange sequences an interpret
45 them as numbers. What is shown here is an attempt to approximate what it
49 TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
50 DecimalInteger: ["+" | "-"] ("0"..."9")+
51 HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
52 BinInteger: "0b" ("0" | "1")+
54 One aspect to note is that the :token:`DecimalInteger` token *includes* the
55 ``+`` or ``-``, as opposed to having ``+`` and ``-`` be unary operators as
58 Also note that :token:`BinInteger` creates a value of type ``bits<n>``
59 (where ``n`` is the number of bits). This will implicitly convert to
62 TableGen has identifier-like tokens:
65 ualpha: "a"..."z" | "A"..."Z" | "_"
66 TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
67 TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*
69 Note that unlike most languages, TableGen allows :token:`TokIdentifier` to
70 begin with a number. In case of ambiguity, a token will be interpreted as a
71 numeric literal rather than an identifier.
73 TableGen also has two string-like literals:
76 TokString: '"' <non-'"' characters and C-like escapes> '"'
77 TokCodeFragment: "[{" <shortest text not containing "}]"> "}]"
79 :token:`TokCodeFragment` is essentially a multiline string literal
80 delimited by ``[{`` and ``}]``.
83 The current implementation accepts the following C-like escapes::
87 TableGen also has the following keywords::
89 bit bits class code dag
90 def foreach defm field in
91 int let list multiclass string
93 TableGen also has "bang operators" which have a
94 wide variety of meanings:
98 :!eq !if !head !tail !con
99 :!add !shl !sra !srl !and
100 :!cast !empty !subst !foreach !listconcat !strconcat
105 TableGen has an ``include`` mechanism. It does not play a role in the
106 syntax per se, since it is lexically replaced with the contents of the
110 IncludeDirective: "include" `TokString`
112 TableGen's top-level production consists of "objects".
115 TableGenFile: `Object`*
116 Object: `Class` | `Def` | `Defm` | `Let` | `MultiClass` | `Foreach`
122 Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
124 A ``class`` declaration creates a record which other records can inherit
125 from. A class can be parametrized by a list of "template arguments", whose
126 values can be used in the class body.
128 A given class can only be defined once. A ``class`` declaration is
129 considered to define the class if any of the following is true:
131 .. break ObjectBody into its consituents so that they are present here?
133 #. The :token:`TemplateArgList` is present.
134 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
135 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
137 You can declare an empty class by giving and empty :token:`TemplateArgList`
138 and an empty :token:`ObjectBody`. This can serve as a restricted form of
139 forward declaration: note that records deriving from the forward-declared
140 class will inherit no fields from it since the record expansion is done
141 when the record is parsed.
144 TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
149 .. Omitting mention of arcane "field" prefix to discourage its use.
151 The declaration syntax is pretty much what you would expect as a C++
155 Declaration: `Type` `TokIdentifier` ["=" `Value`]
157 It assigns the value to the identifer.
163 Type: "string" | "code" | "bit" | "int" | "dag"
164 :| "bits" "<" `TokInteger` ">"
165 :| "list" "<" `Type` ">"
167 ClassID: `TokIdentifier`
169 Both ``string`` and ``code`` correspond to the string type; the difference
170 is purely to indicate programmer intention.
172 The :token:`ClassID` must identify a class that has been previously
179 Value: `SimpleValue` `ValueSuffix`*
180 ValueSuffix: "{" `RangeList` "}"
181 :| "[" `RangeList` "]"
182 :| "." `TokIdentifier`
183 RangeList: `RangePiece` ("," `RangePiece`)*
184 RangePiece: `TokInteger`
185 :| `TokInteger` "-" `TokInteger`
186 :| `TokInteger` `TokInteger`
188 The peculiar last form of :token:`RangePiece` is due to the fact that the
189 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
190 two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,
191 instead of "1", "-", and "5".
192 The :token:`RangeList` can be thought of as specifying "list slice" in some
196 :token:`SimpleValue` has a number of forms:
200 SimpleValue: `TokIdentifier`
202 The value will be the variable referenced by the identifier. It can be one
205 .. The code for this is exceptionally abstruse. These examples are a
208 * name of a ``def``, such as the use of ``Bar`` in::
210 def Bar : SomeClass {
218 * value local to a ``def``, such as the use of ``Bar`` in::
225 * a template arg of a ``class``, such as the use of ``Bar`` in::
231 * value local to a ``multiclass``, such as the use of ``Bar`` in::
238 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
240 multiclass Foo<int Bar> {
245 SimpleValue: `TokInteger`
247 This represents the numeric value of the integer.
250 SimpleValue: `TokString`+
252 Multiple adjacent string literals are concatenated like in C/C++. The value
253 is the concatenation of the strings.
256 SimpleValue: `TokCodeFragment`
258 The value is the string value of the code fragment.
263 ``?`` represents an "unset" initializer.
266 SimpleValue: "{" `ValueList` "}"
267 ValueList: [`ValueListNE`]
268 ValueListNE: `Value` ("," `Value`)*
270 This represents a sequence of bits, as would be used to initialize a
271 ``bits<n>`` field (where ``n`` is the number of bits).
274 SimpleValue: `ClassID` "<" `ValueListNE` ">"
276 This generates a new anonymous record definition (as would be created by an
277 unnamed ``def`` inheriting from the given class with the given template
278 arguments) and the value is the value of that record definition.
281 SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]
283 A list initializer. The optional :token:`Type` can be used to indicate a
284 specific element type, otherwise the element type will be deduced from the
287 .. The initial `DagArg` of the dag must start with an identifier or
288 !cast, but this is more of an implementation detail and so for now just
292 SimpleValue: "(" `DagArg` `DagArgList` ")"
293 DagArgList: `DagArg` ("," `DagArg`)*
294 DagArg: `Value` [":" `TokVarName`] | `TokVarName`
296 The initial :token:`DagArg` is called the "operator" of the dag.
299 SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
305 ObjectBody: `BaseClassList` `Body`
306 BaseClassList: [":" `BaseClassListNE`]
307 BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*
308 SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]
309 DefmID: `TokIdentifier`
311 The version with the :token:`MultiClassID` is only valid in the
312 :token:`BaseClassList` of a ``defm``.
313 The :token:`MultiClassID` should be the name of a ``multiclass``.
315 .. put this somewhere else
317 It is after parsing the base class list that the "let stack" is applied.
320 Body: ";" | "{" BodyList "}"
322 BodyItem: `Declaration` ";"
323 :| "let" `TokIdentifier` [`RangeList`] "=" `Value` ";"
325 The ``let`` form allows overriding the value of an inherited field.
331 There can be pastes in the names here, like ``#NAME#``. Look into that
332 and document it (it boils down to ParseIDValue with IDParseMode ==
333 ParseNameMode). ParseObjectName calls into the general ParseValue, with
334 the only different from "arbitrary expression parsing" being IDParseMode
338 Def: "def" `TokIdentifier` `ObjectBody`
340 Defines a record whose name is given by the :token:`TokIdentifier`. The
341 fields of the record are inherited from the base classes and defined in the
344 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
351 Defm: "defm" `TokIdentifier` ":" `BaseClassListNE` ";"
353 Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must
354 precede any ``class``'s that appear.
360 Foreach: "foreach" `Declaration` "in" "{" `Object`* "}"
361 :| "foreach" `Declaration` "in" `Object`
363 The value assigned to the variable in the declaration is iterated over and
364 the object or object list is reevaluated with the variable set at each
371 Let: "let" `LetList` "in" "{" `Object`* "}"
372 :| "let" `LetList` "in" `Object`
373 LetList: `LetItem` ("," `LetItem`)*
374 LetItem: `TokIdentifier` [`RangeList`] "=" `Value`
376 This is effectively equivalent to ``let`` inside the body of a record
377 except that it applies to multiple records at a time. The bindings are
378 applied at the end of parsing the base classes of a record.
384 MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
385 : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"
386 BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*
387 MultiClassID: `TokIdentifier`
388 MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`