docs/TableGenFundamentals.rst

   1 .. _tablegen:
   2
   3 =====================
   4 TableGen Fundamentals
   5 =====================
   6
   7 .. contents::
   8    :local:
   9
  10 Introduction
  11 ============
  12
  13 TableGen's purpose is to help a human develop and maintain records of
  14 domain-specific information.  Because there may be a large number of these
  15 records, it is specifically designed to allow writing flexible descriptions and
  16 for common features of these records to be factored out.  This reduces the
  17 amount of duplication in the description, reduces the chance of error, and makes
  18 it easier to structure domain specific information.
  19
  20 The core part of TableGen `parses a file`_, instantiates the declarations, and
  21 hands the result off to a domain-specific `TableGen backend`_ for processing.
  22 The current major user of TableGen is the `LLVM code
  23 generator <CodeGenerator.html>`_.
  24
  25 Note that if you work on TableGen much, and use emacs or vim, that you can find
  26 an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
  27 ``llvm/utils/vim`` directories of your LLVM distribution, respectively.
  28
  29 .. _intro:
  30
  31 Basic concepts
  32 --------------
  33
  34 TableGen files consist of two key parts: 'classes' and 'definitions', both of
  35 which are considered 'records'.
  36
  37 **TableGen records** have a unique name, a list of values, and a list of
  38 superclasses.  The list of values is the main data that TableGen builds for each
  39 record; it is this that holds the domain specific information for the
  40 application.  The interpretation of this data is left to a specific `TableGen
  41 backend`_, but the structure and format rules are taken care of and are fixed by
  42 TableGen.
  43
  44 **TableGen definitions** are the concrete form of 'records'.  These generally do
  45 not have any undefined values, and are marked with the '``def``' keyword.
  46
  47 **TableGen classes** are abstract records that are used to build and describe
  48 other records.  These 'classes' allow the end-user to build abstractions for
  49 either the domain they are targeting (such as "Register", "RegisterClass", and
  50 "Instruction" in the LLVM code generator) or for the implementor to help factor
  51 out common properties of records (such as "FPInst", which is used to represent
  52 floating point instructions in the X86 backend).  TableGen keeps track of all of
  53 the classes that are used to build up a definition, so the backend can find all
  54 definitions of a particular class, such as "Instruction".
  55
  56 **TableGen multiclasses** are groups of abstract records that are instantiated
  57 all at once.  Each instantiation can result in multiple TableGen definitions.
  58 If a multiclass inherits from another multiclass, the definitions in the
  59 sub-multiclass become part of the current multiclass, as if they were declared
  60 in the current multiclass.
  61
  62 .. _described above:
  63
  64 An example record
  65 -----------------
  66
  67 With no other arguments, TableGen parses the specified file and prints out all
  68 of the classes, then all of the definitions.  This is a good way to see what the
  69 various definitions expand to fully.  Running this on the ``X86.td`` file prints
  70 this (at the time of this writing):
  71
  72 .. code-block:: llvm
  73
  74   ...
  75   def ADD32rr {   // Instruction X86Inst I
  76     string Namespace = "X86";
  77     dag OutOperandList = (outs GR32:$dst);
  78     dag InOperandList = (ins GR32:$src1, GR32:$src2);
  79     string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
  80     list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
  81     list<Register> Uses = [];
  82     list<Register> Defs = [EFLAGS];
  83     list<Predicate> Predicates = [];
  84     int CodeSize = 3;
  85     int AddedComplexity = 0;
  86     bit isReturn = 0;
  87     bit isBranch = 0;
  88     bit isIndirectBranch = 0;
  89     bit isBarrier = 0;
  90     bit isCall = 0;
  91     bit canFoldAsLoad = 0;
  92     bit mayLoad = 0;
  93     bit mayStore = 0;
  94     bit isImplicitDef = 0;
  95     bit isConvertibleToThreeAddress = 1;
  96     bit isCommutable = 1;
  97     bit isTerminator = 0;
  98     bit isReMaterializable = 0;
  99     bit isPredicable = 0;
 100     bit hasDelaySlot = 0;
 101     bit usesCustomInserter = 0;
 102     bit hasCtrlDep = 0;
 103     bit isNotDuplicable = 0;
 104     bit hasSideEffects = 0;
 105     bit neverHasSideEffects = 0;
 106     InstrItinClass Itinerary = NoItinerary;
 107     string Constraints = "";
 108     string DisableEncoding = "";
 109     bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
 110     Format Form = MRMDestReg;
 111     bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
 112     ImmType ImmT = NoImm;
 113     bits<3> ImmTypeBits = { 0, 0, 0 };
 114     bit hasOpSizePrefix = 0;
 115     bit hasAdSizePrefix = 0;
 116     bits<4> Prefix = { 0, 0, 0, 0 };
 117     bit hasREX_WPrefix = 0;
 118     FPFormat FPForm = ?;
 119     bits<3> FPFormBits = { 0, 0, 0 };
 120   }
 121   ...
 122
 123 This definition corresponds to a 32-bit register-register add instruction in the
 124 X86.  The string after the '``def``' string indicates the name of the
 125 record---"``ADD32rr``" in this case---and the comment at the end of the line
 126 indicates the superclasses of the definition.  The body of the record contains
 127 all of the data that TableGen assembled for the record, indicating that the
 128 instruction is part of the "X86" namespace, the pattern indicating how the the
 129 instruction should be emitted into the assembly file, that it is a two-address
 130 instruction, has a particular encoding, etc.  The contents and semantics of the
 131 information in the record is specific to the needs of the X86 backend, and is
 132 only shown as an example.
 133
 134 As you can see, a lot of information is needed for every instruction supported
 135 by the code generator, and specifying it all manually would be unmaintainable,
 136 prone to bugs, and tiring to do in the first place.  Because we are using
 137 TableGen, all of the information was derived from the following definition:
 138
 139 .. code-block:: llvm
 140
 141   let Defs = [EFLAGS],
 142       isCommutable = 1,                  // X = ADD Y,Z --> X = ADD Z,Y
 143       isConvertibleToThreeAddress = 1 in // Can transform into LEA.
 144   def ADD32rr  : I<0x01, MRMDestReg, (outs GR32:$dst),
 145                                      (ins GR32:$src1, GR32:$src2),
 146                    "add{l}\t{$src2, $dst|$dst, $src2}",
 147                    [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
 148
 149 This definition makes use of the custom class ``I`` (extended from the custom
 150 class ``X86Inst``), which is defined in the X86-specific TableGen file, to
 151 factor out the common features that instructions of its class share.  A key
 152 feature of TableGen is that it allows the end-user to define the abstractions
 153 they prefer to use when describing their information.
 154
 155 Each def record has a special entry called "``NAME``."  This is the name of the
 156 def ("``ADD32rr``" above).  In the general case def names can be formed from
 157 various kinds of string processing expressions and ``NAME`` resolves to the
 158 final value obtained after resolving all of those expressions.  The user may
 159 refer to ``NAME`` anywhere she desires to use the ultimate name of the def.
 160 ``NAME`` should not be defined anywhere else in user code to avoid conflict
 161 problems.
 162
 163 Running TableGen
 164 ----------------
 165
 166 TableGen runs just like any other LLVM tool.  The first (optional) argument
 167 specifies the file to read.  If a filename is not specified, ``llvm-tblgen``
 168 reads from standard input.
 169
 170 To be useful, one of the `TableGen backends`_ must be used.  These backends are
 171 selectable on the command line (type '``llvm-tblgen -help``' for a list).  For
 172 example, to get a list of all of the definitions that subclass a particular type
 173 (which can be useful for building up an enum list of these records), use the
 174 ``-print-enums`` option:
 175
 176 .. code-block:: bash
 177
 178   $ llvm-tblgen X86.td -print-enums -class=Register
 179   AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
 180   ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
 181   MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
 182   R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
 183   R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
 184   RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
 185   XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
 186   XMM6, XMM7, XMM8, XMM9,
 187
 188   $ llvm-tblgen X86.td -print-enums -class=Instruction
 189   ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
 190   ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
 191   ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
 192   ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
 193   ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
 194
 195 The default backend prints out all of the records, as `described above`_.
 196
 197 If you plan to use TableGen, you will most likely have to `write a backend`_
 198 that extracts the information specific to what you need and formats it in the
 199 appropriate way.
 200
 201 .. _parses a file:
 202
 203 TableGen syntax
 204 ===============
 205
 206 TableGen doesn't care about the meaning of data (that is up to the backend to
 207 define), but it does care about syntax, and it enforces a simple type system.
 208 This section describes the syntax and the constructs allowed in a TableGen file.
 209
 210 TableGen primitives
 211 -------------------
 212
 213 TableGen comments
 214 ^^^^^^^^^^^^^^^^^
 215
 216 TableGen supports BCPL style "``//``" comments, which run to the end of the
 217 line, and it also supports **nestable** "``/* */``" comments.
 218
 219 .. _TableGen type:
 220
 221 The TableGen type system
 222 ^^^^^^^^^^^^^^^^^^^^^^^^
 223
 224 TableGen files are strongly typed, in a simple (but complete) type-system.
 225 These types are used to perform automatic conversions, check for errors, and to
 226 help interface designers constrain the input that they allow.  Every `value
 227 definition`_ is required to have an associated type.
 228
 229 TableGen supports a mixture of very low-level types (such as ``bit``) and very
 230 high-level types (such as ``dag``).  This flexibility is what allows it to
 231 describe a wide range of information conveniently and compactly.  The TableGen
 232 types are:
 233
 234 ``bit``
 235     A 'bit' is a boolean value that can hold either 0 or 1.
 236
 237 ``int``
 238     The 'int' type represents a simple 32-bit integer value, such as 5.
 239
 240 ``string``
 241     The 'string' type represents an ordered sequence of characters of arbitrary
 242     length.
 243
 244 ``bits<n>``
 245     A 'bits' type is an arbitrary, but fixed, size integer that is broken up
 246     into individual bits.  This type is useful because it can handle some bits
 247     being defined while others are undefined.
 248
 249 ``list<ty>``
 250     This type represents a list whose elements are some other type.  The
 251     contained type is arbitrary: it can even be another list type.
 252
 253 Class type
 254     Specifying a class name in a type context means that the defined value must
 255     be a subclass of the specified class.  This is useful in conjunction with
 256     the **``list``** type, for example, to constrain the elements of the list to
 257     a common base class (e.g., a ``**list**<Register>`` can only contain
 258     definitions derived from the "``Register``" class).
 259
 260 ``dag``
 261     This type represents a nestable directed graph of elements.
 262
 263 ``code``
 264     This represents a big hunk of text.  This is lexically distinct from string
 265     values because it doesn't require escaping double quotes and other common
 266     characters that occur in code.
 267
 268 To date, these types have been sufficient for describing things that TableGen
 269 has been used for, but it is straight-forward to extend this list if needed.
 270
 271 .. _TableGen expressions:
 272
 273 TableGen values and expressions
 274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 275
 276 TableGen allows for a pretty reasonable number of different expression forms
 277 when building up values.  These forms allow the TableGen file to be written in a
 278 natural syntax and flavor for the application.  The current expression forms
 279 supported include:
 280
 281 ``?``
 282     uninitialized field
 283
 284 ``0b1001011``
 285     binary integer value
 286
 287 ``07654321``
 288     octal integer value (indicated by a leading 0)
 289
 290 ``7``
 291     decimal integer value
 292
 293 ``0x7F``
 294     hexadecimal integer value
 295
 296 ``"foo"``
 297     string value
 298
 299 ``[{ ... }]``
 300     code fragment
 301
 302 ``[ X, Y, Z ]<type>``
 303     list value.  <type> is the type of the list element and is usually optional.
 304     In rare cases, TableGen is unable to deduce the element type in which case
 305     the user must specify it explicitly.
 306
 307 ``{ a, b, c }``
 308     initializer for a "bits<3>" value
 309
 310 ``value``
 311     value reference
 312
 313 ``value{17}``
 314     access to one bit of a value
 315
 316 ``value{15-17}``
 317     access to multiple bits of a value
 318
 319 ``DEF``
 320     reference to a record definition
 321
 322 ``CLASS<val list>``
 323     reference to a new anonymous definition of CLASS with the specified template
 324     arguments.
 325
 326 ``X.Y``
 327     reference to the subfield of a value
 328
 329 ``list[4-7,17,2-3]``
 330     A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
 331     Elements may be included multiple times.
 332
 333 ``foreach <var> = [ <list> ] in { <body> }``
 334
 335 ``foreach <var> = [ <list> ] in <def>``
 336     Replicate <body> or <def>, replacing instances of <var> with each value
 337     in <list>.  <var> is scoped at the level of the ``foreach`` loop and must
 338     not conflict with any other object introduced in <body> or <def>.  Currently
 339     only ``def``\s are expanded within <body>.
 340
 341 ``foreach <var> = 0-15 in ...``
 342
 343 ``foreach <var> = {0-15,32-47} in ...``
 344     Loop over ranges of integers. The braces are required for multiple ranges.
 345
 346 ``(DEF a, b)``
 347     a dag value.  The first element is required to be a record definition, the
 348     remaining elements in the list may be arbitrary other values, including
 349     nested ```dag``' values.
 350
 351 ``!strconcat(a, b)``
 352     A string value that is the result of concatenating the 'a' and 'b' strings.
 353
 354 ``str1#str2``
 355     "#" (paste) is a shorthand for !strconcat.  It may concatenate things that
 356     are not quoted strings, in which case an implicit !cast<string> is done on
 357     the operand of the paste.</dd>
 358
 359 ``!cast<type>(a)``
 360     A symbol of type *type* obtained by looking up the string 'a' in the symbol
 361     table.  If the type of 'a' does not match *type*, TableGen aborts with an
 362     error. !cast<string> is a special case in that the argument must be an
 363     object defined by a 'def' construct.</dd>
 364
 365 ``!subst(a, b, c)``
 366     If 'a' and 'b' are of string type or are symbol references, substitute 'b'
 367     for 'a' in 'c.'  This operation is analogous to $(subst) in GNU make.
 368
 369 ``!foreach(a, b, c)``
 370     For each member 'b' of dag or list 'a' apply operator 'c.'  'b' is a dummy
 371     variable that should be declared as a member variable of an instantiated
 372     class.  This operation is analogous to $(foreach) in GNU make.
 373
 374 ``!head(a)``
 375     The first element of list 'a.'
 376
 377 ``!tail(a)``
 378     The 2nd-N elements of list 'a.'
 379
 380 ``!empty(a)``
 381     An integer {0,1} indicating whether list 'a' is empty.
 382
 383 ``!if(a,b,c)``
 384   'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
 385
 386 ``!eq(a,b)``
 387     'bit 1' if string a is equal to string b, 0 otherwise.  This only operates
 388     on string, int and bit objects.  Use !cast<string> to compare other types of
 389     objects.
 390
 391 Note that all of the values have rules specifying how they convert to values
 392 for different types.  These rules allow you to assign a value like "``7``"
 393 to a "``bits<4>``" value, for example.
 394
 395 Classes and definitions
 396 -----------------------
 397
 398 As mentioned in the `intro`_, classes and definitions (collectively known as
 399 'records') in TableGen are the main high-level unit of information that TableGen
 400 collects.  Records are defined with a ``def`` or ``class`` keyword, the record
 401 name, and an optional list of "`template arguments`_".  If the record has
 402 superclasses, they are specified as a comma separated list that starts with a
 403 colon character ("``:``").  If `value definitions`_ or `let expressions`_ are
 404 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
 405 the record ends with a semicolon.
 406
 407 Here is a simple TableGen file:
 408
 409 .. code-block:: llvm
 410
 411   class C { bit V = 1; }
 412   def X : C;
 413   def Y : C {
 414     string Greeting = "hello";
 415   }
 416
 417 This example defines two definitions, ``X`` and ``Y``, both of which derive from
 418 the ``C`` class.  Because of this, they both get the ``V`` bit value.  The ``Y``
 419 definition also gets the Greeting member as well.
 420
 421 In general, classes are useful for collecting together the commonality between a
 422 group of records and isolating it in a single place.  Also, classes permit the
 423 specification of default values for their subclasses, allowing the subclasses to
 424 override them as they wish.
 425
 426 .. _value definition:
 427 .. _value definitions:
 428
 429 Value definitions
 430 ^^^^^^^^^^^^^^^^^
 431
 432 Value definitions define named entries in records.  A value must be defined
 433 before it can be referred to as the operand for another value definition or
 434 before the value is reset with a `let expression`_.  A value is defined by
 435 specifying a `TableGen type`_ and a name.  If an initial value is available, it
 436 may be specified after the type with an equal sign.  Value definitions require
 437 terminating semicolons.
 438
 439 .. _let expression:
 440 .. _let expressions:
 441 .. _"let" expressions within a record:
 442
 443 'let' expressions
 444 ^^^^^^^^^^^^^^^^^
 445
 446 A record-level let expression is used to change the value of a value definition
 447 in a record.  This is primarily useful when a superclass defines a value that a
 448 derived class or definition wants to override.  Let expressions consist of the
 449 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
 450 value.  For example, a new class could be added to the example above, redefining
 451 the ``V`` field for all of its subclasses:
 452
 453 .. code-block:: llvm
 454
 455   class D : C { let V = 0; }
 456   def Z : D;
 457
 458 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
 459 despite the fact that it derives (indirectly) from the ``C`` class, because the
 460 ``D`` class overrode its value.
 461
 462 .. _template arguments:
 463
 464 Class template arguments
 465 ^^^^^^^^^^^^^^^^^^^^^^^^
 466
 467 TableGen permits the definition of parameterized classes as well as normal
 468 concrete classes.  Parameterized TableGen classes specify a list of variable
 469 bindings (which may optionally have defaults) that are bound when used.  Here is
 470 a simple example:
 471
 472 .. code-block:: llvm
 473
 474   class FPFormat<bits<3> val> {
 475     bits<3> Value = val;
 476   }
 477   def NotFP      : FPFormat<0>;
 478   def ZeroArgFP  : FPFormat<1>;
 479   def OneArgFP   : FPFormat<2>;
 480   def OneArgFPRW : FPFormat<3>;
 481   def TwoArgFP   : FPFormat<4>;
 482   def CompareFP  : FPFormat<5>;
 483   def CondMovFP  : FPFormat<6>;
 484   def SpecialFP  : FPFormat<7>;
 485
 486 In this case, template arguments are used as a space efficient way to specify a
 487 list of "enumeration values", each with a "``Value``" field set to the specified
 488 integer.
 489
 490 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
 491 with template arguments.  As an example:
 492
 493 .. code-block:: llvm
 494
 495   class ModRefVal<bits<2> val> {
 496     bits<2> Value = val;
 497   }
 498
 499   def None   : ModRefVal<0>;
 500   def Mod    : ModRefVal<1>;
 501   def Ref    : ModRefVal<2>;
 502   def ModRef : ModRefVal<3>;
 503
 504   class Value<ModRefVal MR> {
 505     // Decode some information into a more convenient format, while providing
 506     // a nice interface to the user of the "Value" class.
 507     bit isMod = MR.Value{0};
 508     bit isRef = MR.Value{1};
 509
 510     // other stuff...
 511   }
 512
 513   // Example uses
 514   def bork : Value<Mod>;
 515   def zork : Value<Ref>;
 516   def hork : Value<ModRef>;
 517
 518 This is obviously a contrived example, but it shows how template arguments can
 519 be used to decouple the interface provided to the user of the class from the
 520 actual internal data representation expected by the class.  In this case,
 521 running ``llvm-tblgen`` on the example prints the following definitions:
 522
 523 .. code-block:: llvm
 524
 525   def bork {      // Value
 526     bit isMod = 1;
 527     bit isRef = 0;
 528   }
 529   def hork {      // Value
 530     bit isMod = 1;
 531     bit isRef = 1;
 532   }
 533   def zork {      // Value
 534     bit isMod = 0;
 535     bit isRef = 1;
 536   }
 537
 538 This shows that TableGen was able to dig into the argument and extract a piece
 539 of information that was requested by the designer of the "Value" class.  For
 540 more realistic examples, please see existing users of TableGen, such as the X86
 541 backend.
 542
 543 Multiclass definitions and instances
 544 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 545
 546 While classes with template arguments are a good way to factor commonality
 547 between two instances of a definition, multiclasses allow a convenient notation
 548 for defining multiple definitions at once (instances of implicitly constructed
 549 classes).  For example, consider an 3-address instruction set whose instructions
 550 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
 551 (e.g. SPARC). In this case, you'd like to specify in one place that this
 552 commonality exists, then in a separate place indicate what all the ops are.
 553
 554 Here is an example TableGen fragment that shows this idea:
 555
 556 .. code-block:: llvm
 557
 558   def ops;
 559   def GPR;
 560   def Imm;
 561   class inst<int opc, string asmstr, dag operandlist>;
 562
 563   multiclass ri_inst<int opc, string asmstr> {
 564     def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
 565                    (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
 566     def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
 567                    (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
 568   }
 569
 570   // Instantiations of the ri_inst multiclass.
 571   defm ADD : ri_inst<0b111, "add">;
 572   defm SUB : ri_inst<0b101, "sub">;
 573   defm MUL : ri_inst<0b100, "mul">;
 574   ...
 575
 576 The name of the resultant definitions has the multidef fragment names appended
 577 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc.  A defm may
 578 inherit from multiple multiclasses, instantiating definitions from each
 579 multiclass.  Using a multiclass this way is exactly equivalent to instantiating
 580 the classes multiple times yourself, e.g. by writing:
 581
 582 .. code-block:: llvm
 583
 584   def ops;
 585   def GPR;
 586   def Imm;
 587   class inst<int opc, string asmstr, dag operandlist>;
 588
 589   class rrinst<int opc, string asmstr>
 590     : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
 591            (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
 592
 593   class riinst<int opc, string asmstr>
 594     : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
 595            (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
 596
 597   // Instantiations of the ri_inst multiclass.
 598   def ADD_rr : rrinst<0b111, "add">;
 599   def ADD_ri : riinst<0b111, "add">;
 600   def SUB_rr : rrinst<0b101, "sub">;
 601   def SUB_ri : riinst<0b101, "sub">;
 602   def MUL_rr : rrinst<0b100, "mul">;
 603   def MUL_ri : riinst<0b100, "mul">;
 604   ...
 605
 606 A ``defm`` can also be used inside a multiclass providing several levels of
 607 multiclass instanciations.
 608
 609 .. code-block:: llvm
 610
 611   class Instruction<bits<4> opc, string Name> {
 612     bits<4> opcode = opc;
 613     string name = Name;
 614   }
 615
 616   multiclass basic_r<bits<4> opc> {
 617     def rr : Instruction<opc, "rr">;
 618     def rm : Instruction<opc, "rm">;
 619   }
 620
 621   multiclass basic_s<bits<4> opc> {
 622     defm SS : basic_r<opc>;
 623     defm SD : basic_r<opc>;
 624     def X : Instruction<opc, "x">;
 625   }
 626
 627   multiclass basic_p<bits<4> opc> {
 628     defm PS : basic_r<opc>;
 629     defm PD : basic_r<opc>;
 630     def Y : Instruction<opc, "y">;
 631   }
 632
 633   defm ADD : basic_s<0xf>, basic_p<0xf>;
 634   ...
 635
 636   // Results
 637   def ADDPDrm { ...
 638   def ADDPDrr { ...
 639   def ADDPSrm { ...
 640   def ADDPSrr { ...
 641   def ADDSDrm { ...
 642   def ADDSDrr { ...
 643   def ADDY { ...
 644   def ADDX { ...
 645
 646 ``defm`` declarations can inherit from classes too, the rule to follow is that
 647 the class list must start after the last multiclass, and there must be at least
 648 one multiclass before them.
 649
 650 .. code-block:: llvm
 651
 652   class XD { bits<4> Prefix = 11; }
 653   class XS { bits<4> Prefix = 12; }
 654
 655   class I<bits<4> op> {
 656     bits<4> opcode = op;
 657   }
 658
 659   multiclass R {
 660     def rr : I<4>;
 661     def rm : I<2>;
 662   }
 663
 664   multiclass Y {
 665     defm SS : R, XD;
 666     defm SD : R, XS;
 667   }
 668
 669   defm Instr : Y;
 670
 671   // Results
 672   def InstrSDrm {
 673     bits<4> opcode = { 0, 0, 1, 0 };
 674     bits<4> Prefix = { 1, 1, 0, 0 };
 675   }
 676   ...
 677   def InstrSSrr {
 678     bits<4> opcode = { 0, 1, 0, 0 };
 679     bits<4> Prefix = { 1, 0, 1, 1 };
 680   }
 681
 682 File scope entities
 683 -------------------
 684
 685 File inclusion
 686 ^^^^^^^^^^^^^^
 687
 688 TableGen supports the '``include``' token, which textually substitutes the
 689 specified file in place of the include directive.  The filename should be
 690 specified as a double quoted string immediately after the '``include``' keyword.
 691 Example:
 692
 693 .. code-block:: llvm
 694
 695   include "foo.td"
 696
 697 'let' expressions
 698 ^^^^^^^^^^^^^^^^^
 699
 700 "Let" expressions at file scope are similar to `"let" expressions within a
 701 record`_, except they can specify a value binding for multiple records at a
 702 time, and may be useful in certain other cases.  File-scope let expressions are
 703 really just another way that TableGen allows the end-user to factor out
 704 commonality from the records.
 705
 706 File-scope "let" expressions take a comma-separated list of bindings to apply,
 707 and one or more records to bind the values in.  Here are some examples:
 708
 709 .. code-block:: llvm
 710
 711   let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
 712     def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
 713
 714   let isCall = 1 in
 715     // All calls clobber the non-callee saved registers...
 716     let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
 717                 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
 718                 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
 719       def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
 720                              "call\t${dst:call}", []>;
 721       def CALL32r     : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
 722                           "call\t{*}$dst", [(X86call GR32:$dst)]>;
 723       def CALL32m     : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
 724                           "call\t{*}$dst", []>;
 725     }
 726
 727 File-scope "let" expressions are often useful when a couple of definitions need
 728 to be added to several records, and the records do not otherwise need to be
 729 opened, as in the case with the ``CALL*`` instructions above.
 730
 731 It's also possible to use "let" expressions inside multiclasses, providing more
 732 ways to factor out commonality from the records, specially if using several
 733 levels of multiclass instanciations. This also avoids the need of using "let"
 734 expressions within subsequent records inside a multiclass.
 735
 736 .. code-block:: llvm
 737
 738   multiclass basic_r<bits<4> opc> {
 739     let Predicates = [HasSSE2] in {
 740       def rr : Instruction<opc, "rr">;
 741       def rm : Instruction<opc, "rm">;
 742     }
 743     let Predicates = [HasSSE3] in
 744       def rx : Instruction<opc, "rx">;
 745   }
 746
 747   multiclass basic_ss<bits<4> opc> {
 748     let IsDouble = 0 in
 749       defm SS : basic_r<opc>;
 750
 751     let IsDouble = 1 in
 752       defm SD : basic_r<opc>;
 753   }
 754
 755   defm ADD : basic_ss<0xf>;
 756
 757 Looping
 758 ^^^^^^^
 759
 760 TableGen supports the '``foreach``' block, which textually replicates the loop
 761 body, substituting iterator values for iterator references in the body.
 762 Example:
 763
 764 .. code-block:: llvm
 765
 766   foreach i = [0, 1, 2, 3] in {
 767     def R#i : Register<...>;
 768     def F#i : Register<...>;
 769   }
 770
 771 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``.  ``foreach`` blocks
 772 may be nested. If there is only one item in the body the braces may be
 773 elided:
 774
 775 .. code-block:: llvm
 776
 777   foreach i = [0, 1, 2, 3] in
 778     def R#i : Register<...>;
 779
 780 Code Generator backend info
 781 ===========================
 782
 783 Expressions used by code generator to describe instructions and isel patterns:
 784
 785 ``(implicit a)``
 786     an implicitly defined physical register.  This tells the dag instruction
 787     selection emitter the input pattern's extra definitions matches implicit
 788     physical register definitions.
 789
 790 .. _TableGen backend:
 791 .. _TableGen backends:
 792 .. _write a backend:
 793
 794 TableGen backends
 795 =================
 796
 797 TODO: How they work, how to write one.  This section should not contain details
 798 about any particular backend, except maybe ``-print-enums`` as an example.  This
 799 should highlight the APIs in ``TableGen/Record.h``.