1.. _tablegen: 2 3===================== 4TableGen Fundamentals 5===================== 6 7.. contents:: 8 :local: 9 10Introduction 11============ 12 13TableGen's purpose is to help a human develop and maintain records of 14domain-specific information. Because there may be a large number of these 15records, it is specifically designed to allow writing flexible descriptions and 16for common features of these records to be factored out. This reduces the 17amount of duplication in the description, reduces the chance of error, and makes 18it easier to structure domain specific information. 19 20The core part of TableGen `parses a file`_, instantiates the declarations, and 21hands the result off to a domain-specific `TableGen backend`_ for processing. 22The current major user of TableGen is the `LLVM code 23generator <CodeGenerator.html>`_. 24 25Note that if you work on TableGen much, and use emacs or vim, that you can find 26an 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 31Basic concepts 32-------------- 33 34TableGen files consist of two key parts: 'classes' and 'definitions', both of 35which are considered 'records'. 36 37**TableGen records** have a unique name, a list of values, and a list of 38superclasses. The list of values is the main data that TableGen builds for each 39record; it is this that holds the domain specific information for the 40application. The interpretation of this data is left to a specific `TableGen 41backend`_, but the structure and format rules are taken care of and are fixed by 42TableGen. 43 44**TableGen definitions** are the concrete form of 'records'. These generally do 45not 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 48other records. These 'classes' allow the end-user to build abstractions for 49either the domain they are targeting (such as "Register", "RegisterClass", and 50"Instruction" in the LLVM code generator) or for the implementor to help factor 51out common properties of records (such as "FPInst", which is used to represent 52floating point instructions in the X86 backend). TableGen keeps track of all of 53the classes that are used to build up a definition, so the backend can find all 54definitions of a particular class, such as "Instruction". 55 56**TableGen multiclasses** are groups of abstract records that are instantiated 57all at once. Each instantiation can result in multiple TableGen definitions. 58If a multiclass inherits from another multiclass, the definitions in the 59sub-multiclass become part of the current multiclass, as if they were declared 60in the current multiclass. 61 62.. _described above: 63 64An example record 65----------------- 66 67With no other arguments, TableGen parses the specified file and prints out all 68of the classes, then all of the definitions. This is a good way to see what the 69various definitions expand to fully. Running this on the ``X86.td`` file prints 70this (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 123This definition corresponds to a 32-bit register-register add instruction in the 124X86. The string after the '``def``' string indicates the name of the 125record---"``ADD32rr``" in this case---and the comment at the end of the line 126indicates the superclasses of the definition. The body of the record contains 127all of the data that TableGen assembled for the record, indicating that the 128instruction is part of the "X86" namespace, the pattern indicating how the the 129instruction should be emitted into the assembly file, that it is a two-address 130instruction, has a particular encoding, etc. The contents and semantics of the 131information in the record is specific to the needs of the X86 backend, and is 132only shown as an example. 133 134As you can see, a lot of information is needed for every instruction supported 135by the code generator, and specifying it all manually would be unmaintainable, 136prone to bugs, and tiring to do in the first place. Because we are using 137TableGen, 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 149This definition makes use of the custom class ``I`` (extended from the custom 150class ``X86Inst``), which is defined in the X86-specific TableGen file, to 151factor out the common features that instructions of its class share. A key 152feature of TableGen is that it allows the end-user to define the abstractions 153they prefer to use when describing their information. 154 155Each def record has a special entry called "``NAME``." This is the name of the 156def ("``ADD32rr``" above). In the general case def names can be formed from 157various kinds of string processing expressions and ``NAME`` resolves to the 158final value obtained after resolving all of those expressions. The user may 159refer 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 161problems. 162 163Running TableGen 164---------------- 165 166TableGen runs just like any other LLVM tool. The first (optional) argument 167specifies the file to read. If a filename is not specified, ``llvm-tblgen`` 168reads from standard input. 169 170To be useful, one of the `TableGen backends`_ must be used. These backends are 171selectable on the command line (type '``llvm-tblgen -help``' for a list). For 172example, 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 195The default backend prints out all of the records, as `described above`_. 196 197If you plan to use TableGen, you will most likely have to `write a backend`_ 198that extracts the information specific to what you need and formats it in the 199appropriate way. 200 201.. _parses a file: 202 203TableGen syntax 204=============== 205 206TableGen doesn't care about the meaning of data (that is up to the backend to 207define), but it does care about syntax, and it enforces a simple type system. 208This section describes the syntax and the constructs allowed in a TableGen file. 209 210TableGen primitives 211------------------- 212 213TableGen comments 214^^^^^^^^^^^^^^^^^ 215 216TableGen supports BCPL style "``//``" comments, which run to the end of the 217line, and it also supports **nestable** "``/* */``" comments. 218 219.. _TableGen type: 220 221The TableGen type system 222^^^^^^^^^^^^^^^^^^^^^^^^ 223 224TableGen files are strongly typed, in a simple (but complete) type-system. 225These types are used to perform automatic conversions, check for errors, and to 226help interface designers constrain the input that they allow. Every `value 227definition`_ is required to have an associated type. 228 229TableGen supports a mixture of very low-level types (such as ``bit``) and very 230high-level types (such as ``dag``). This flexibility is what allows it to 231describe a wide range of information conveniently and compactly. The TableGen 232types 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 253Class 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 a 257 common base class (e.g., a ``list<Register>`` can only contain definitions 258 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 268To date, these types have been sufficient for describing things that TableGen 269has been used for, but it is straight-forward to extend this list if needed. 270 271.. _TableGen expressions: 272 273TableGen values and expressions 274^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 275 276TableGen allows for a pretty reasonable number of different expression forms 277when building up values. These forms allow the TableGen file to be written in a 278natural syntax and flavor for the application. The current expression forms 279supported 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. 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. 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 391Note that all of the values have rules specifying how they convert to values 392for different types. These rules allow you to assign a value like "``7``" 393to a "``bits<4>``" value, for example. 394 395Classes and definitions 396----------------------- 397 398As mentioned in the `intro`_, classes and definitions (collectively known as 399'records') in TableGen are the main high-level unit of information that TableGen 400collects. Records are defined with a ``def`` or ``class`` keyword, the record 401name, and an optional list of "`template arguments`_". If the record has 402superclasses, they are specified as a comma separated list that starts with a 403colon character ("``:``"). If `value definitions`_ or `let expressions`_ are 404needed for the class, they are enclosed in curly braces ("``{}``"); otherwise, 405the record ends with a semicolon. 406 407Here 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 417This example defines two definitions, ``X`` and ``Y``, both of which derive from 418the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y`` 419definition also gets the Greeting member as well. 420 421In general, classes are useful for collecting together the commonality between a 422group of records and isolating it in a single place. Also, classes permit the 423specification of default values for their subclasses, allowing the subclasses to 424override them as they wish. 425 426.. _value definition: 427.. _value definitions: 428 429Value definitions 430^^^^^^^^^^^^^^^^^ 431 432Value definitions define named entries in records. A value must be defined 433before it can be referred to as the operand for another value definition or 434before the value is reset with a `let expression`_. A value is defined by 435specifying a `TableGen type`_ and a name. If an initial value is available, it 436may be specified after the type with an equal sign. Value definitions require 437terminating semicolons. 438 439.. _let expression: 440.. _let expressions: 441.. _"let" expressions within a record: 442 443'let' expressions 444^^^^^^^^^^^^^^^^^ 445 446A record-level let expression is used to change the value of a value definition 447in a record. This is primarily useful when a superclass defines a value that a 448derived 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 450value. For example, a new class could be added to the example above, redefining 451the ``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 458In this case, the ``Z`` definition will have a zero value for its ``V`` value, 459despite the fact that it derives (indirectly) from the ``C`` class, because the 460``D`` class overrode its value. 461 462.. _template arguments: 463 464Class template arguments 465^^^^^^^^^^^^^^^^^^^^^^^^ 466 467TableGen permits the definition of parameterized classes as well as normal 468concrete classes. Parameterized TableGen classes specify a list of variable 469bindings (which may optionally have defaults) that are bound when used. Here is 470a 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 486In this case, template arguments are used as a space efficient way to specify a 487list of "enumeration values", each with a "``Value``" field set to the specified 488integer. 489 490The more esoteric forms of `TableGen expressions`_ are useful in conjunction 491with 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 518This is obviously a contrived example, but it shows how template arguments can 519be used to decouple the interface provided to the user of the class from the 520actual internal data representation expected by the class. In this case, 521running ``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 538This shows that TableGen was able to dig into the argument and extract a piece 539of information that was requested by the designer of the "Value" class. For 540more realistic examples, please see existing users of TableGen, such as the X86 541backend. 542 543Multiclass definitions and instances 544^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 545 546While classes with template arguments are a good way to factor commonality 547between two instances of a definition, multiclasses allow a convenient notation 548for defining multiple definitions at once (instances of implicitly constructed 549classes). For example, consider an 3-address instruction set whose instructions 550come 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 552commonality exists, then in a separate place indicate what all the ops are. 553 554Here 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 576The name of the resultant definitions has the multidef fragment names appended 577to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may 578inherit from multiple multiclasses, instantiating definitions from each 579multiclass. Using a multiclass this way is exactly equivalent to instantiating 580the 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 606A ``defm`` can also be used inside a multiclass providing several levels of 607multiclass 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 647the class list must start after the last multiclass, and there must be at least 648one 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 682File scope entities 683------------------- 684 685File inclusion 686^^^^^^^^^^^^^^ 687 688TableGen supports the '``include``' token, which textually substitutes the 689specified file in place of the include directive. The filename should be 690specified as a double quoted string immediately after the '``include``' keyword. 691Example: 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 701record`_, except they can specify a value binding for multiple records at a 702time, and may be useful in certain other cases. File-scope let expressions are 703really just another way that TableGen allows the end-user to factor out 704commonality from the records. 705 706File-scope "let" expressions take a comma-separated list of bindings to apply, 707and 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 727File-scope "let" expressions are often useful when a couple of definitions need 728to be added to several records, and the records do not otherwise need to be 729opened, as in the case with the ``CALL*`` instructions above. 730 731It's also possible to use "let" expressions inside multiclasses, providing more 732ways to factor out commonality from the records, specially if using several 733levels of multiclass instanciations. This also avoids the need of using "let" 734expressions 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 757Looping 758^^^^^^^ 759 760TableGen supports the '``foreach``' block, which textually replicates the loop 761body, substituting iterator values for iterator references in the body. 762Example: 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 771This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks 772may be nested. If there is only one item in the body the braces may be 773elided: 774 775.. code-block:: llvm 776 777 foreach i = [0, 1, 2, 3] in 778 def R#i : Register<...>; 779 780Code Generator backend info 781=========================== 782 783Expressions 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 794TableGen backends 795================= 796 797TODO: How they work, how to write one. This section should not contain details 798about any particular backend, except maybe ``-print-enums`` as an example. This 799should highlight the APIs in ``TableGen/Record.h``. 800