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