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
  93 TableGen also has "bang operators" which have a
  94 wide variety of meanings:
  95
  96 .. productionlist::
  97    BangOperator: one of
  98                :!eq     !if      !head    !tail      !con
  99                :!add    !shl     !sra     !srl       !and
 100                :!or     !empty   !subst   !foreach   !strconcat
 101                :!cast   !listconcat       !size      !foldl
 102                :!isa    !dag     !le      !lt        !ge
 103                :!gt     !ne      !mul     !listsplat
 104
 105 TableGen also has !cond operator that needs a slightly different
 106 syntax compared to other "bang operators":
 107
 108 .. productionlist::
 109    CondOperator: !cond
 110
 111
 112 Syntax
 113 ======
 114
 115 TableGen has an ``include`` mechanism. It does not play a role in the
 116 syntax per se, since it is lexically replaced with the contents of the
 117 included file.
 118
 119 .. productionlist::
 120    IncludeDirective: "include" `TokString`
 121
 122 TableGen's top-level production consists of "objects".
 123
 124 .. productionlist::
 125    TableGenFile: `Object`*
 126    Object: `Class` | `Def` | `Defm` | `Defset` | `Let` | `MultiClass` |
 127            `Foreach`
 128
 129 ``class``\es
 130 ------------
 131
 132 .. productionlist::
 133    Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
 134    TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
 135
 136 A ``class`` declaration creates a record which other records can inherit
 137 from. A class can be parametrized by a list of "template arguments", whose
 138 values can be used in the class body.
 139
 140 A given class can only be defined once. A ``class`` declaration is
 141 considered to define the class if any of the following is true:
 142
 143 .. break ObjectBody into its consituents so that they are present here?
 144
 145 #. The :token:`TemplateArgList` is present.
 146 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
 147 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
 148
 149 You can declare an empty class by giving an empty :token:`TemplateArgList`
 150 and an empty :token:`ObjectBody`. This can serve as a restricted form of
 151 forward declaration: note that records deriving from the forward-declared
 152 class will inherit no fields from it since the record expansion is done
 153 when the record is parsed.
 154
 155 Every class has an implicit template argument called ``NAME``, which is set
 156 to the name of the instantiating ``def`` or ``defm``. The result is undefined
 157 if the class is instantiated by an anonymous record.
 158
 159 Declarations
 160 ------------
 161
 162 .. Omitting mention of arcane "field" prefix to discourage its use.
 163
 164 The declaration syntax is pretty much what you would expect as a C++
 165 programmer.
 166
 167 .. productionlist::
 168    Declaration: `Type` `TokIdentifier` ["=" `Value`]
 169
 170 It assigns the value to the identifier.
 171
 172 Types
 173 -----
 174
 175 .. productionlist::
 176    Type: "string" | "code" | "bit" | "int" | "dag"
 177        :| "bits" "<" `TokInteger` ">"
 178        :| "list" "<" `Type` ">"
 179        :| `ClassID`
 180    ClassID: `TokIdentifier`
 181
 182 Both ``string`` and ``code`` correspond to the string type; the difference
 183 is purely to indicate programmer intention.
 184
 185 The :token:`ClassID` must identify a class that has been previously
 186 declared or defined.
 187
 188 Values
 189 ------
 190
 191 .. productionlist::
 192    Value: `SimpleValue` `ValueSuffix`*
 193    ValueSuffix: "{" `RangeList` "}"
 194               :| "[" `RangeList` "]"
 195               :| "." `TokIdentifier`
 196    RangeList: `RangePiece` ("," `RangePiece`)*
 197    RangePiece: `TokInteger`
 198              :| `TokInteger` "-" `TokInteger`
 199              :| `TokInteger` `TokInteger`
 200
 201 The peculiar last form of :token:`RangePiece` is due to the fact that the
 202 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
 203 two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,
 204 instead of "1", "-", and "5".
 205 The :token:`RangeList` can be thought of as specifying "list slice" in some
 206 contexts.
 207
 208
 209 :token:`SimpleValue` has a number of forms:
 210
 211
 212 .. productionlist::
 213    SimpleValue: `TokIdentifier`
 214
 215 The value will be the variable referenced by the identifier. It can be one
 216 of:
 217
 218 .. The code for this is exceptionally abstruse. These examples are a
 219    best-effort attempt.
 220
 221 * name of a ``def``, such as the use of ``Bar`` in::
 222
 223      def Bar : SomeClass {
 224        int X = 5;
 225      }
 226
 227      def Foo {
 228        SomeClass Baz = Bar;
 229      }
 230
 231 * value local to a ``def``, such as the use of ``Bar`` in::
 232
 233      def Foo {
 234        int Bar = 5;
 235        int Baz = Bar;
 236      }
 237
 238   Values defined in superclasses can be accessed the same way.
 239
 240 * a template arg of a ``class``, such as the use of ``Bar`` in::
 241
 242      class Foo<int Bar> {
 243        int Baz = Bar;
 244      }
 245
 246 * value local to a ``class``, such as the use of ``Bar`` in::
 247
 248      class Foo {
 249        int Bar = 5;
 250        int Baz = Bar;
 251      }
 252
 253 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
 254
 255      multiclass Foo<int Bar> {
 256        def : SomeClass<Bar>;
 257      }
 258
 259 * the iteration variable of a ``foreach``, such as the use of ``i`` in::
 260
 261      foreach i = 0-5 in
 262      def Foo#i;
 263
 264 * a variable defined by ``defset``
 265
 266 * the implicit template argument ``NAME`` in a ``class`` or ``multiclass``
 267
 268 .. productionlist::
 269    SimpleValue: `TokInteger`
 270
 271 This represents the numeric value of the integer.
 272
 273 .. productionlist::
 274    SimpleValue: `TokString`+
 275
 276 Multiple adjacent string literals are concatenated like in C/C++. The value
 277 is the concatenation of the strings.
 278
 279 .. productionlist::
 280    SimpleValue: `TokCodeFragment`
 281
 282 The value is the string value of the code fragment.
 283
 284 .. productionlist::
 285    SimpleValue: "?"
 286
 287 ``?`` represents an "unset" initializer.
 288
 289 .. productionlist::
 290    SimpleValue: "{" `ValueList` "}"
 291    ValueList: [`ValueListNE`]
 292    ValueListNE: `Value` ("," `Value`)*
 293
 294 This represents a sequence of bits, as would be used to initialize a
 295 ``bits<n>`` field (where ``n`` is the number of bits).
 296
 297 .. productionlist::
 298    SimpleValue: `ClassID` "<" `ValueListNE` ">"
 299
 300 This generates a new anonymous record definition (as would be created by an
 301 unnamed ``def`` inheriting from the given class with the given template
 302 arguments) and the value is the value of that record definition.
 303
 304 .. productionlist::
 305    SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]
 306
 307 A list initializer. The optional :token:`Type` can be used to indicate a
 308 specific element type, otherwise the element type will be deduced from the
 309 given values.
 310
 311 .. The initial `DagArg` of the dag must start with an identifier or
 312    !cast, but this is more of an implementation detail and so for now just
 313    leave it out.
 314
 315 .. productionlist::
 316    SimpleValue: "(" `DagArg` [`DagArgList`] ")"
 317    DagArgList: `DagArg` ("," `DagArg`)*
 318    DagArg: `Value` [":" `TokVarName`] | `TokVarName`
 319
 320 The initial :token:`DagArg` is called the "operator" of the dag.
 321
 322 .. productionlist::
 323    SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
 324               :| `CondOperator` "(" `CondVal` ("," `CondVal`)* ")"
 325    CondVal: `Value` ":" `Value`
 326
 327 Bodies
 328 ------
 329
 330 .. productionlist::
 331    ObjectBody: `BaseClassList` `Body`
 332    BaseClassList: [":" `BaseClassListNE`]
 333    BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*
 334    SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]
 335    DefmID: `TokIdentifier`
 336
 337 The version with the :token:`MultiClassID` is only valid in the
 338 :token:`BaseClassList` of a ``defm``.
 339 The :token:`MultiClassID` should be the name of a ``multiclass``.
 340
 341 .. put this somewhere else
 342
 343 It is after parsing the base class list that the "let stack" is applied.
 344
 345 .. productionlist::
 346    Body: ";" | "{" BodyList "}"
 347    BodyList: BodyItem*
 348    BodyItem: `Declaration` ";"
 349            :| "let" `TokIdentifier` [ "{" `RangeList` "}" ] "=" `Value` ";"
 350
 351 The ``let`` form allows overriding the value of an inherited field.
 352
 353 ``def``
 354 -------
 355
 356 .. productionlist::
 357    Def: "def" [`Value`] `ObjectBody`
 358
 359 Defines a record whose name is given by the optional :token:`Value`. The value
 360 is parsed in a special mode where global identifiers (records and variables
 361 defined by ``defset``) are not recognized, and all unrecognized identifiers
 362 are interpreted as strings.
 363
 364 If no name is given, the record is anonymous. The final name of anonymous
 365 records is undefined, but globally unique.
 366
 367 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
 368 a ``foreach``.
 369
 370 When a non-anonymous record is defined in a multiclass and the given name
 371 does not contain a reference to the implicit template argument ``NAME``, such
 372 a reference will automatically be prepended. That is, the following are
 373 equivalent inside a multiclass::
 374
 375     def Foo;
 376     def NAME#Foo;
 377
 378 ``defm``
 379 --------
 380
 381 .. productionlist::
 382    Defm: "defm" [`Value`] ":" `BaseClassListNE` ";"
 383
 384 The :token:`BaseClassList` is a list of at least one ``multiclass`` and any
 385 number of ``class``'s. The ``multiclass``'s must occur before any ``class``'s.
 386
 387 Instantiates all records defined in all given ``multiclass``'s and adds the
 388 given ``class``'s as superclasses.
 389
 390 The name is parsed in the same special mode used by ``def``. If the name is
 391 missing, a globally unique string is used instead (but instantiated records
 392 are not considered to be anonymous, unless they were originally defined by an
 393 anonymous ``def``) That is, the following have different semantics::
 394
 395     defm : SomeMultiClass<...>;    // some globally unique name
 396     defm "" : SomeMultiClass<...>; // empty name string
 397
 398 When it occurs inside a multiclass, the second variant is equivalent to
 399 ``defm NAME : ...``. More generally, when ``defm`` occurs in a multiclass and
 400 its name does not contain a reference to the implicit template argument
 401 ``NAME``, such a reference will automatically be prepended. That is, the
 402 following are equivalent inside a multiclass::
 403
 404     defm Foo : SomeMultiClass<...>;
 405     defm NAME#Foo : SomeMultiClass<...>;
 406
 407 ``defset``
 408 ----------
 409 .. productionlist::
 410    Defset: "defset" `Type` `TokIdentifier` "=" "{" `Object`* "}"
 411
 412 All records defined inside the braces via ``def`` and ``defm`` are collected
 413 in a globally accessible list of the given name (in addition to being added
 414 to the global collection of records as usual). Anonymous records created inside
 415 initializier expressions using the ``Class<args...>`` syntax are never collected
 416 in a defset.
 417
 418 The given type must be ``list<A>``, where ``A`` is some class. It is an error
 419 to define a record (via ``def`` or ``defm``) inside the braces which doesn't
 420 derive from ``A``.
 421
 422 ``foreach``
 423 -----------
 424
 425 .. productionlist::
 426    Foreach: "foreach" `ForeachDeclaration` "in" "{" `Object`* "}"
 427           :| "foreach" `ForeachDeclaration` "in" `Object`
 428    ForeachDeclaration: ID "=" ( "{" `RangeList` "}" | `RangePiece` | `Value` )
 429
 430 The value assigned to the variable in the declaration is iterated over and
 431 the object or object list is reevaluated with the variable set at each
 432 iterated value.
 433
 434 Note that the productions involving RangeList and RangePiece have precedence
 435 over the more generic value parsing based on the first token.
 436
 437 Top-Level ``let``
 438 -----------------
 439
 440 .. productionlist::
 441    Let:  "let" `LetList` "in" "{" `Object`* "}"
 442       :| "let" `LetList` "in" `Object`
 443    LetList: `LetItem` ("," `LetItem`)*
 444    LetItem: `TokIdentifier` [`RangeList`] "=" `Value`
 445
 446 This is effectively equivalent to ``let`` inside the body of a record
 447 except that it applies to multiple records at a time. The bindings are
 448 applied at the end of parsing the base classes of a record.
 449
 450 ``multiclass``
 451 --------------
 452
 453 .. productionlist::
 454    MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
 455              : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"
 456    BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*
 457    MultiClassID: `TokIdentifier`
 458    MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`
 459
 460 Preprocessing Support
 461 =====================
 462
 463 TableGen's embedded preprocessor is only intended for conditional compilation.
 464 It supports the following directives:
 465
 466 .. productionlist::
 467    LineBegin: ^
 468    LineEnd: "\n" | "\r" | EOF
 469    WhiteSpace: " " | "\t"
 470    CStyleComment: "/*" (.* - "*/") "*/"
 471    BCPLComment: "//" (.* - `LineEnd`) `LineEnd`
 472    WhiteSpaceOrCStyleComment: `WhiteSpace` | `CStyleComment`
 473    WhiteSpaceOrAnyComment: `WhiteSpace` | `CStyleComment` | `BCPLComment`
 474    MacroName: `ualpha` (`ualpha` | "0"..."9")*
 475    PrepDefine: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 476              : "#define" (`WhiteSpace`)+ `MacroName`
 477              : (`WhiteSpaceOrAnyComment`)* `LineEnd`
 478    PrepIfdef: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 479             : "#ifdef" (`WhiteSpace`)+ `MacroName`
 480             : (`WhiteSpaceOrAnyComment`)* `LineEnd`
 481    PrepElse: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 482            : "#else" (`WhiteSpaceOrAnyComment`)* `LineEnd`
 483    PrepEndif: `LineBegin` (`WhiteSpaceOrCStyleComment`)*
 484             : "#endif" (`WhiteSpaceOrAnyComment`)* `LineEnd`
 485    PrepRegContentException: `PrepIfdef` | `PrepElse` | `PrepEndif` | EOF
 486    PrepRegion: .* - `PrepRegContentException`
 487              :| `PrepIfdef`
 488              :  (`PrepRegion`)*
 489              :  [`PrepElse`]
 490              :  (`PrepRegion`)*
 491              :  `PrepEndif`
 492
 493 :token:`PrepRegion` may occur anywhere in a TD file, as long as it matches
 494 the grammar specification.
 495
 496 :token:`PrepDefine` allows defining a :token:`MacroName` so that any following
 497 :token:`PrepIfdef` - :token:`PrepElse` preprocessing region part and
 498 :token:`PrepIfdef` - :token:`PrepEndif` preprocessing region
 499 are enabled for TableGen tokens parsing.
 500
 501 A preprocessing region, starting (i.e. having its :token:`PrepIfdef`) in a file,
 502 must end (i.e. have its :token:`PrepEndif`) in the same file.
 503
 504 A :token:`MacroName` may be defined externally by using ``{ -D<NAME> }``
 505 option of TableGen.