llvm/docs/TableGen/LangRef.rst

   1 ===========================
   2 TableGen Language Reference
   3 ===========================
   4
   5 .. contents::
   6    :local:
   7
   8 .. warning::
   9    This document is extremely rough. If you find something lacking, please
  10    fix it, file a documentation bug, or ask about it on llvm-dev.
  11
  12 Introduction
  13 ============
  14
  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.
  20
  21 Notation
  22 ========
  23
  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.
  29
  30 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
  31
  32 Lexical Analysis
  33 ================
  34
  35 TableGen supports BCPL (``// ...``) and nestable C-style (``/* ... */``)
  36 comments.  TableGen also provides simple `Preprocessing Support`_.
  37
  38 The following is a listing of the basic punctuation tokens::
  39
  40    - + [ ] { } ( ) < > : ; .  = ? #
  41
  42 Numeric literals take one of the following forms:
  43
  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
  46    "should" accept.
  47
  48 .. productionlist::
  49    TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
  50    DecimalInteger: ["+" | "-"] ("0"..."9")+
  51    HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
  52    BinInteger: "0b" ("0" | "1")+
  53
  54 One aspect to note is that the :token:`DecimalInteger` token *includes* the
  55 ``+`` or ``-``, as opposed to having ``+`` and ``-`` be unary operators as
  56 most languages do.
  57
  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
  60 integers when needed.
  61
  62 TableGen has identifier-like tokens:
  63
  64 .. productionlist::
  65    ualpha: "a"..."z" | "A"..."Z" | "_"
  66    TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
  67    TokVarName: "$" `ualpha` (`ualpha` |  "0"..."9")*
  68
  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.
  72
  73 TableGen also has two string-like literals:
  74
  75 .. productionlist::
  76    TokString: '"' <non-'"' characters and C-like escapes> '"'
  77    TokCodeFragment: "[{" <shortest text not containing "}]"> "}]"
  78
  79 :token:`TokCodeFragment` is essentially a multiline string literal
  80 delimited by ``[{`` and ``}]``.
  81
  82 .. note::
  83    The current implementation accepts the following C-like escapes::
  84
  85       \\ \' \" \t \n
  86
  87 TableGen also has the following keywords::
  88
  89    bit   bits      class   code         dag
  90    def   foreach   defm    field        in
  91    int   let       list    multiclass   string
  92    if    then      else
  93
  94 TableGen also has "bang operators" which have a
  95 wide variety of meanings:
  96
  97 .. productionlist::
  98    BangOperator: one of
  99                :!eq     !if      !head    !tail      !con
 100                :!add    !shl     !sra     !srl       !and
 101                :!or     !empty   !subst   !foreach   !strconcat
 102                :!cast   !listconcat       !size      !foldl
 103                :!isa    !dag     !le      !lt        !ge
 104                :!gt     !ne      !mul     !listsplat !setop
 105                :!getop
 106
 107 TableGen also has !cond operator that needs a slightly different
 108 syntax compared to other "bang operators":
 109
 110 .. productionlist::
 111    CondOperator: !cond
 112
 113
 114 Syntax
 115 ======
 116
 117 TableGen has an ``include`` mechanism. It does not play a role in the
 118 syntax per se, since it is lexically replaced with the contents of the
 119 included file.
 120
 121 .. productionlist::
 122    IncludeDirective: "include" `TokString`
 123
 124 TableGen's top-level production consists of "objects".
 125
 126 .. productionlist::
 127    TableGenFile: `Object`*
 128    Object: `Class` | `Def` | `Defm` | `Defset` | `Defvar` | `Let` |
 129            `MultiClass` | `Foreach` | `If`
 130
 131 ``class``\es
 132 ------------
 133
 134 .. productionlist::
 135    Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
 136    TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
 137
 138 A ``class`` declaration creates a record which other records can inherit
 139 from. A class can be parametrized by a list of "template arguments", whose
 140 values can be used in the class body.
 141
 142 A given class can only be defined once. A ``class`` declaration is
 143 considered to define the class if any of the following is true:
 144
 145 .. break ObjectBody into its constituents so that they are present here?
 146
 147 #. The :token:`TemplateArgList` is present.
 148 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
 149 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
 150
 151 You can declare an empty class by giving an empty :token:`TemplateArgList`
 152 and an empty :token:`ObjectBody`. This can serve as a restricted form of
 153 forward declaration: note that records deriving from the forward-declared
 154 class will inherit no fields from it since the record expansion is done
 155 when the record is parsed.
 156
 157 Every class has an implicit template argument called ``NAME``, which is set
 158 to the name of the instantiating ``def`` or ``defm``. The result is undefined
 159 if the class is instantiated by an anonymous record.
 160
 161 Declarations
 162 ------------
 163
 164 .. Omitting mention of arcane "field" prefix to discourage its use.
 165
 166 The declaration syntax is pretty much what you would expect as a C++
 167 programmer.
 168
 169 .. productionlist::
 170    Declaration: `Type` `TokIdentifier` ["=" `Value`]
 171
 172 It assigns the value to the identifier.
 173
 174 Types
 175 -----
 176
 177 .. productionlist::
 178    Type: "string" | "code" | "bit" | "int" | "dag"
 179        :| "bits" "<" `TokInteger` ">"
 180        :| "list" "<" `Type` ">"
 181        :| `ClassID`
 182    ClassID: `TokIdentifier`
 183
 184 Both ``string`` and ``code`` correspond to the string type; the difference
 185 is purely to indicate programmer intention.
 186
 187 The :token:`ClassID` must identify a class that has been previously
 188 declared or defined.
 189
 190 Values
 191 ------
 192
 193 .. productionlist::
 194    Value: `SimpleValue` `ValueSuffix`*
 195    ValueSuffix: "{" `RangeList` "}"
 196               :| "[" `RangeList` "]"
 197               :| "." `TokIdentifier`
 198    RangeList: `RangePiece` ("," `RangePiece`)*
 199    RangePiece: `TokInteger`
 200              :| `TokInteger` "-" `TokInteger`
 201              :| `TokInteger` `TokInteger`
 202
 203 The peculiar last form of :token:`RangePiece` is due to the fact that the
 204 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
 205 two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,
 206 instead of "1", "-", and "5".
 207 The :token:`RangeList` can be thought of as specifying "list slice" in some
 208 contexts.
 209
 210
 211 :token:`SimpleValue` has a number of forms:
 212
 213
 214 .. productionlist::
 215    SimpleValue: `TokIdentifier`
 216
 217 The value will be the variable referenced by the identifier. It can be one
 218 of:
 219
 220 .. The code for this is exceptionally abstruse. These examples are a
 221    best-effort attempt.
 222
 223 * name of a ``def``, such as the use of ``Bar`` in::
 224
 225      def Bar : SomeClass {
 226        int X = 5;
 227      }
 228
 229      def Foo {
 230        SomeClass Baz = Bar;
 231      }
 232
 233 * value local to a ``def``, such as the use of ``Bar`` in::
 234
 235      def Foo {
 236        int Bar = 5;
 237        int Baz = Bar;
 238      }
 239
 240   Values defined in superclasses can be accessed the same way.
 241
 242 * a template arg of a ``class``, such as the use of ``Bar`` in::
 243
 244      class Foo<int Bar> {
 245        int Baz = Bar;
 246      }
 247
 248 * value local to a ``class``, such as the use of ``Bar`` in::
 249
 250      class Foo {
 251        int Bar = 5;
 252        int Baz = Bar;
 253      }
 254
 255 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
 256
 257      multiclass Foo<int Bar> {
 258        def : SomeClass<Bar>;
 259      }
 260
 261 * the iteration variable of a ``foreach``, such as the use of ``i`` in::
 262
 263      foreach i = 0-5 in
 264      def Foo#i;
 265
 266 * a variable defined by ``defset`` or ``defvar``
 267
 268 * the implicit template argument ``NAME`` in a ``class`` or ``multiclass``
 269
 270 .. productionlist::
 271    SimpleValue: `TokInteger`
 272
 273 This represents the numeric value of the integer.
 274
 275 .. productionlist::
 276    SimpleValue: `TokString`+
 277
 278 Multiple adjacent string literals are concatenated like in C/C++. The value
 279 is the concatenation of the strings.
 280
 281 .. productionlist::
 282    SimpleValue: `TokCodeFragment`
 283
 284 The value is the string value of the code fragment.
 285
 286 .. productionlist::
 287    SimpleValue: "?"
 288
 289 ``?`` represents an "unset" initializer.
 290
 291 .. productionlist::
 292    SimpleValue: "{" `ValueList` "}"
 293    ValueList: [`ValueListNE`]
 294    ValueListNE: `Value` ("," `Value`)*
 295
 296 This represents a sequence of bits, as would be used to initialize a
 297 ``bits<n>`` field (where ``n`` is the number of bits).
 298
 299 .. productionlist::
 300    SimpleValue: `ClassID` "<" `ValueListNE` ">"
 301
 302 This generates a new anonymous record definition (as would be created by an
 303 unnamed ``def`` inheriting from the given class with the given template
 304 arguments) and the value is the value of that record definition.
 305
 306 .. productionlist::
 307    SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]
 308
 309 A list initializer. The optional :token:`Type` can be used to indicate a
 310 specific element type, otherwise the element type will be deduced from the
 311 given values.
 312
 313 .. The initial `DagArg` of the dag must start with an identifier or
 314    !cast, but this is more of an implementation detail and so for now just
 315    leave it out.
 316
 317 .. productionlist::
 318    SimpleValue: "(" `DagArg` [`DagArgList`] ")"
 319    DagArgList: `DagArg` ("," `DagArg`)*
 320    DagArg: `Value` [":" `TokVarName`] | `TokVarName`
 321
 322 The initial :token:`DagArg` is called the "operator" of the dag.
 323
 324 .. productionlist::
 325    SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
 326               :| `CondOperator` "(" `CondVal` ("," `CondVal`)* ")"
 327    CondVal: `Value` ":" `Value`
 328
 329 Bodies
 330 ------
 331
 332 .. productionlist::
 333    ObjectBody: `BaseClassList` `Body`
 334    BaseClassList: [":" `BaseClassListNE`]
 335    BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*
 336    SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]
 337    DefmID: `TokIdentifier`
 338
 339 The version with the :token:`MultiClassID` is only valid in the
 340 :token:`BaseClassList` of a ``defm``.
 341 The :token:`MultiClassID` should be the name of a ``multiclass``.
 342
 343 .. put this somewhere else
 344
 345 It is after parsing the base class list that the "let stack" is applied.
 346
 347 .. productionlist::
 348    Body: ";" | "{" BodyList "}"
 349    BodyList: BodyItem*
 350    BodyItem: `Declaration` ";"
 351            :| "let" `TokIdentifier` [ "{" `RangeList` "}" ] "=" `Value` ";"
 352            :| `Defvar`
 353
 354 The ``let`` form allows overriding the value of an inherited field.
 355
 356 ``def``
 357 -------
 358
 359 .. productionlist::
 360    Def: "def" [`Value`] `ObjectBody`
 361
 362 Defines a record whose name is given by the optional :token:`Value`. The value
 363 is parsed in a special mode where global identifiers (records and variables
 364 defined by ``defset``, and variables defined at global scope by ``defvar``) are
 365 not recognized, and all unrecognized identifiers are interpreted as strings.
 366
 367 If no name is given, the record is anonymous. The final name of anonymous
 368 records is undefined, but globally unique.
 369
 370 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
 371 a ``foreach``.
 372
 373 When a non-anonymous record is defined in a multiclass and the given name
 374 does not contain a reference to the implicit template argument ``NAME``, such
 375 a reference will automatically be prepended. That is, the following are
 376 equivalent inside a multiclass::
 377
 378     def Foo;
 379     def NAME#Foo;
 380
 381 ``defm``
 382 --------
 383
 384 .. productionlist::
 385    Defm: "defm" [`Value`] ":" `BaseClassListNE` ";"
 386
 387 The :token:`BaseClassList` is a list of at least one ``multiclass`` and any
 388 number of ``class``'s. The ``multiclass``'s must occur before any ``class``'s.
 389
 390 Instantiates all records defined in all given ``multiclass``'s and adds the
 391 given ``class``'s as superclasses.
 392
 393 The name is parsed in the same special mode used by ``def``. If the name is
 394 missing, a globally unique string is used instead (but instantiated records
 395 are not considered to be anonymous, unless they were originally defined by an
 396 anonymous ``def``) That is, the following have different semantics::
 397
 398     defm : SomeMultiClass<...>;    // some globally unique name
 399     defm "" : SomeMultiClass<...>; // empty name string
 400
 401 When it occurs inside a multiclass, the second variant is equivalent to
 402 ``defm NAME : ...``. More generally, when ``defm`` occurs in a multiclass and
 403 its name does not contain a reference to the implicit template argument
 404 ``NAME``, such a reference will automatically be prepended. That is, the
 405 following are equivalent inside a multiclass::
 406
 407     defm Foo : SomeMultiClass<...>;
 408     defm NAME#Foo : SomeMultiClass<...>;
 409
 410 ``defset``
 411 ----------
 412 .. productionlist::
 413    Defset: "defset" `Type` `TokIdentifier` "=" "{" `Object`* "}"
 414
 415 All records defined inside the braces via ``def`` and ``defm`` are collected
 416 in a globally accessible list of the given name (in addition to being added
 417 to the global collection of records as usual). Anonymous records created inside
 418 initializier expressions using the ``Class<args...>`` syntax are never collected
 419 in a defset.
 420
 421 The given type must be ``list<A>``, where ``A`` is some class. It is an error
 422 to define a record (via ``def`` or ``defm``) inside the braces which doesn't
 423 derive from ``A``.
 424
 425 ``defvar``
 426 ----------
 427 .. productionlist::
 428    Defvar: "defvar" `TokIdentifier` "=" `Value` ";"
 429
 430 The identifier on the left of the ``=`` is defined to be a global or local
 431 variable, whose value is given by the expression on the right of the ``=``. The
 432 type of the variable is automatically inferred.
 433
 434 A ``defvar`` statement at the top level of the file defines a global variable,
 435 in the same scope used by ``defset``. If a ``defvar`` statement appears inside
 436 any other construction, including classes, multiclasses and ``foreach``
 437 statements, then the variable is scoped to the inside of that construction
 438 only.
 439
 440 In contexts where the ``defvar`` statement will be encountered multiple times,
 441 the definition is re-evaluated for each instance. For example, a ``defvar``
 442 inside a ``foreach`` can construct a value based on the iteration variable,
 443 which will be different every time round the loop; a ``defvar`` inside a
 444 templated class or multiclass can have a definition depending on the template
 445 parameters.
 446
 447 Variables local to a ``foreach`` go out of scope at the end of each loop
 448 iteration, so their previous value is not accessible in the next iteration. (It
 449 won't work to ``defvar i=!add(i,1)`` each time you go round the loop.)
 450
 451 In general, ``defvar`` variables are immutable once they are defined. It is an
 452 error to define the same variable name twice in the same scope (but legal to
 453 shadow the first definition temporarily in an inner scope).
 454
 455 ``foreach``
 456 -----------
 457
 458 .. productionlist::
 459    Foreach: "foreach" `ForeachDeclaration` "in" "{" `Object`* "}"
 460           :| "foreach" `ForeachDeclaration` "in" `Object`
 461    ForeachDeclaration: ID "=" ( "{" `RangeList` "}" | `RangePiece` | `Value` )
 462
 463 The value assigned to the variable in the declaration is iterated over and
 464 the object or object list is reevaluated with the variable set at each
 465 iterated value.
 466
 467 Note that the productions involving RangeList and RangePiece have precedence
 468 over the more generic value parsing based on the first token.
 469
 470 ``if``
 471 ------
 472
 473 .. productionlist::
 474    If: "if" `Value` "then" `IfBody`
 475      :| "if" `Value` "then" `IfBody` "else" `IfBody`
 476    IfBody: "{" `Object`* "}" | `Object`
 477
 478 The value expression after the ``if`` keyword is evaluated, and if it evaluates
 479 to true (in the same sense used by the ``!if`` operator), then the object
 480 definition(s) after the ``then`` keyword are executed. Otherwise, if there is
 481 an ``else`` keyword, the definition(s) after the ``else`` are executed instead.
 482
 483 Because the braces around the ``then`` clause are optional, this grammar rule
 484 has the usual ambiguity about dangling ``else`` clauses, and it is resolved in
 485 the usual way: in a case like ``if v1 then if v2 then {...} else {...}``, the
 486 ``else`` binds to the inner ``if`` rather than the outer one.
 487
 488 Top-Level ``let``
 489 -----------------
 490
 491 .. productionlist::
 492    Let:  "let" `LetList` "in" "{" `Object`* "}"
 493       :| "let" `LetList` "in" `Object`
 494    LetList: `LetItem` ("," `LetItem`)*
 495    LetItem: `TokIdentifier` [`RangeList`] "=" `Value`
 496
 497 This is effectively equivalent to ``let`` inside the body of a record
 498 except that it applies to multiple records at a time. The bindings are
 499 applied at the end of parsing the base classes of a record.
 500
 501 ``multiclass``
 502 --------------
 503
 504 .. productionlist::
 505    MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
 506              : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"
 507    BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*
 508    MultiClassID: `TokIdentifier`
 509    MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`
 510
 511 Preprocessing Support
 512 =====================
 513
 514 TableGen's embedded preprocessor is only intended for conditional compilation.
 515 It supports the following directives:
 516
 517 .. productionlist::
 518    LineBegin: ^
 519    LineEnd: "\n" | "\r" | EOF
 520    WhiteSpace: " " | "\t"
 521    CStyleComment: "/*" (.* - "*/") "*/"
 522    BCPLComment: "//" (.* - `LineEnd`) `LineEnd`
 523    WhiteSpaceOrCStyleComment: `WhiteSpace` | `CStyleComment`
 524    WhiteSpaceOrAnyComment: `WhiteSpace` | `CStyleComment` | `BCPLComment`
 525    MacroName: `ualpha` (`ualpha` | "0"..."9")*
 526    PrepDefine: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 527              : "#define" (`WhiteSpace`)+ `MacroName`
 528              : (`WhiteSpaceOrAnyComment`)* `LineEnd`
 529    PrepIfdef: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 530             : "#ifdef" (`WhiteSpace`)+ `MacroName`
 531             : (`WhiteSpaceOrAnyComment`)* `LineEnd`
 532    PrepElse: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 533            : "#else" (`WhiteSpaceOrAnyComment`)* `LineEnd`
 534    PrepEndif: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 535             : "#endif" (`WhiteSpaceOrAnyComment`)* `LineEnd`
 536    PrepRegContentException: `PrepIfdef` | `PrepElse` | `PrepEndif` | EOF
 537    PrepRegion: .* - `PrepRegContentException`
 538              :| `PrepIfdef`
 539              :  (`PrepRegion`)*
 540              :  [`PrepElse`]
 541              :  (`PrepRegion`)*
 542              :  `PrepEndif`
 543
 544 :token:`PrepRegion` may occur anywhere in a TD file, as long as it matches
 545 the grammar specification.
 546
 547 :token:`PrepDefine` allows defining a :token:`MacroName` so that any following
 548 :token:`PrepIfdef` - :token:`PrepElse` preprocessing region part and
 549 :token:`PrepIfdef` - :token:`PrepEndif` preprocessing region
 550 are enabled for TableGen tokens parsing.
 551
 552 A preprocessing region, starting (i.e. having its :token:`PrepIfdef`) in a file,
 553 must end (i.e. have its :token:`PrepEndif`) in the same file.
 554
 555 A :token:`MacroName` may be defined externally by using ``{ -D<NAME> }``
 556 option of TableGen.