docs/MIRLangRef.rst

   1 ========================================
   2 Machine IR (MIR) Format Reference Manual
   3 ========================================
   4
   5 .. contents::
   6    :local:
   7
   8 .. warning::
   9   This is a work in progress.
  10
  11 Introduction
  12 ============
  13
  14 This document is a reference manual for the Machine IR (MIR) serialization
  15 format. MIR is a human readable serialization format that is used to represent
  16 LLVM's :ref:`machine specific intermediate representation
  17 <machine code representation>`.
  18
  19 The MIR serialization format is designed to be used for testing the code
  20 generation passes in LLVM.
  21
  22 Overview
  23 ========
  24
  25 The MIR serialization format uses a YAML container. YAML is a standard
  26 data serialization language, and the full YAML language spec can be read at
  27 `yaml.org
  28 <http://www.yaml.org/spec/1.2/spec.html#Introduction>`_.
  29
  30 A MIR file is split up into a series of `YAML documents`_. The first document
  31 can contain an optional embedded LLVM IR module, and the rest of the documents
  32 contain the serialized machine functions.
  33
  34 .. _YAML documents: http://www.yaml.org/spec/1.2/spec.html#id2800132
  35
  36 MIR Testing Guide
  37 =================
  38
  39 You can use the MIR format for testing in two different ways:
  40
  41 - You can write MIR tests that invoke a single code generation pass using the
  42   ``-run-pass`` option in llc.
  43
  44 - You can use llc's ``-stop-after`` option with existing or new LLVM assembly
  45   tests and check the MIR output of a specific code generation pass.
  46
  47 Testing Individual Code Generation Passes
  48 -----------------------------------------
  49
  50 The ``-run-pass`` option in llc allows you to create MIR tests that invoke just
  51 a single code generation pass. When this option is used, llc will parse an
  52 input MIR file, run the specified code generation pass(es), and output the
  53 resulting MIR code.
  54
  55 You can generate an input MIR file for the test by using the ``-stop-after`` or
  56 ``-stop-before`` option in llc. For example, if you would like to write a test
  57 for the post register allocation pseudo instruction expansion pass, you can
  58 specify the machine copy propagation pass in the ``-stop-after`` option, as it
  59 runs just before the pass that we are trying to test:
  60
  61    ``llc -stop-after=machine-cp bug-trigger.ll > test.mir``
  62
  63 After generating the input MIR file, you'll have to add a run line that uses
  64 the ``-run-pass`` option to it. In order to test the post register allocation
  65 pseudo instruction expansion pass on X86-64, a run line like the one shown
  66 below can be used:
  67
  68     ``# RUN: llc -o - %s -mtriple=x86_64-- -run-pass=postrapseudos | FileCheck %s``
  69
  70 The MIR files are target dependent, so they have to be placed in the target
  71 specific test directories (``lib/CodeGen/TARGETNAME``). They also need to
  72 specify a target triple or a target architecture either in the run line or in
  73 the embedded LLVM IR module.
  74
  75 Simplifying MIR files
  76 ^^^^^^^^^^^^^^^^^^^^^
  77
  78 The MIR code coming out of ``-stop-after``/``-stop-before`` is very verbose;
  79 Tests are more accessible and future proof when simplified:
  80
  81 - Use the ``-simplify-mir`` option with llc.
  82
  83 - Machine function attributes often have default values or the test works just
  84   as well with default values. Typical candidates for this are: `alignment:`,
  85   `exposesReturnsTwice`, `legalized`, `regBankSelected`, `selected`.
  86   The whole `frameInfo` section is often unnecessary if there is no special
  87   frame usage in the function. `tracksRegLiveness` on the other hand is often
  88   necessary for some passes that care about block livein lists.
  89
  90 - The (global) `liveins:` list is typically only interesting for early
  91   instruction selection passes and can be removed when testing later passes.
  92   The per-block `liveins:` on the other hand are necessary if
  93   `tracksRegLiveness` is true.
  94
  95 - Branch probability data in block `successors:` lists can be dropped if the
  96   test doesn't depend on it. Example:
  97   `successors: %bb.1(0x40000000), %bb.2(0x40000000)` can be replaced with
  98   `successors: %bb.1, %bb.2`.
  99
 100 - MIR code contains a whole IR module. This is necessary because there are
 101   no equivalents in MIR for global variables, references to external functions,
 102   function attributes, metadata, debug info. Instead some MIR data references
 103   the IR constructs. You can often remove them if the test doesn't depend on
 104   them.
 105
 106 - Alias Analysis is performed on IR values. These are referenced by memory
 107   operands in MIR. Example: `:: (load 8 from %ir.foobar, !alias.scope !9)`.
 108   If the test doesn't depend on (good) alias analysis the references can be
 109   dropped: `:: (load 8)`
 110
 111 - MIR blocks can reference IR blocks for debug printing, profile information
 112   or debug locations. Example: `bb.42.myblock` in MIR references the IR block
 113   `myblock`. It is usually possible to drop the `.myblock` reference and simply
 114   use `bb.42`.
 115
 116 - If there are no memory operands or blocks referencing the IR then the
 117   IR function can be replaced by a parameterless dummy function like
 118   `define @func() { ret void }`.
 119
 120 - It is possible to drop the whole IR section of the MIR file if it only
 121   contains dummy functions (see above). The .mir loader will create the
 122   IR functions automatically in this case.
 123
 124 .. _limitations:
 125
 126 Limitations
 127 -----------
 128
 129 Currently the MIR format has several limitations in terms of which state it
 130 can serialize:
 131
 132 - The target-specific state in the target-specific ``MachineFunctionInfo``
 133   subclasses isn't serialized at the moment.
 134
 135 - The target-specific ``MachineConstantPoolValue`` subclasses (in the ARM and
 136   SystemZ backends) aren't serialized at the moment.
 137
 138 - The ``MCSymbol`` machine operands don't support temporary or local symbols.
 139
 140 - A lot of the state in ``MachineModuleInfo`` isn't serialized - only the CFI
 141   instructions and the variable debug information from MMI is serialized right
 142   now.
 143
 144 These limitations impose restrictions on what you can test with the MIR format.
 145 For now, tests that would like to test some behaviour that depends on the state
 146 of temporary or local ``MCSymbol``  operands or the exception handling state in
 147 MMI, can't use the MIR format. As well as that, tests that test some behaviour
 148 that depends on the state of the target specific ``MachineFunctionInfo`` or
 149 ``MachineConstantPoolValue`` subclasses can't use the MIR format at the moment.
 150
 151 High Level Structure
 152 ====================
 153
 154 .. _embedded-module:
 155
 156 Embedded Module
 157 ---------------
 158
 159 When the first YAML document contains a `YAML block literal string`_, the MIR
 160 parser will treat this string as an LLVM assembly language string that
 161 represents an embedded LLVM IR module.
 162 Here is an example of a YAML document that contains an LLVM module:
 163
 164 .. code-block:: llvm
 165
 166        define i32 @inc(i32* %x) {
 167        entry:
 168          %0 = load i32, i32* %x
 169          %1 = add i32 %0, 1
 170          store i32 %1, i32* %x
 171          ret i32 %1
 172        }
 173
 174 .. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
 175
 176 Machine Functions
 177 -----------------
 178
 179 The remaining YAML documents contain the machine functions. This is an example
 180 of such YAML document:
 181
 182 .. code-block:: text
 183
 184      ---
 185      name:            inc
 186      tracksRegLiveness: true
 187      liveins:
 188        - { reg: '$rdi' }
 189      body: |
 190        bb.0.entry:
 191          liveins: $rdi
 192
 193          $eax = MOV32rm $rdi, 1, _, 0, _
 194          $eax = INC32r killed $eax, implicit-def dead $eflags
 195          MOV32mr killed $rdi, 1, _, 0, _, $eax
 196          RETQ $eax
 197      ...
 198
 199 The document above consists of attributes that represent the various
 200 properties and data structures in a machine function.
 201
 202 The attribute ``name`` is required, and its value should be identical to the
 203 name of a function that this machine function is based on.
 204
 205 The attribute ``body`` is a `YAML block literal string`_. Its value represents
 206 the function's machine basic blocks and their machine instructions.
 207
 208 Machine Instructions Format Reference
 209 =====================================
 210
 211 The machine basic blocks and their instructions are represented using a custom,
 212 human readable serialization language. This language is used in the
 213 `YAML block literal string`_ that corresponds to the machine function's body.
 214
 215 A source string that uses this language contains a list of machine basic
 216 blocks, which are described in the section below.
 217
 218 Machine Basic Blocks
 219 --------------------
 220
 221 A machine basic block is defined in a single block definition source construct
 222 that contains the block's ID.
 223 The example below defines two blocks that have an ID of zero and one:
 224
 225 .. code-block:: text
 226
 227     bb.0:
 228       <instructions>
 229     bb.1:
 230       <instructions>
 231
 232 A machine basic block can also have a name. It should be specified after the ID
 233 in the block's definition:
 234
 235 .. code-block:: text
 236
 237     bb.0.entry:       ; This block's name is "entry"
 238        <instructions>
 239
 240 The block's name should be identical to the name of the IR block that this
 241 machine block is based on.
 242
 243 .. _block-references:
 244
 245 Block References
 246 ^^^^^^^^^^^^^^^^
 247
 248 The machine basic blocks are identified by their ID numbers. Individual
 249 blocks are referenced using the following syntax:
 250
 251 .. code-block:: text
 252
 253     %bb.<id>
 254
 255 Example:
 256
 257 .. code-block:: llvm
 258
 259     %bb.0
 260
 261 The following syntax is also supported, but the former syntax is preferred for
 262 block references:
 263
 264 .. code-block:: text
 265
 266     %bb.<id>[.<name>]
 267
 268 Example:
 269
 270 .. code-block:: llvm
 271
 272     %bb.1.then
 273
 274 Successors
 275 ^^^^^^^^^^
 276
 277 The machine basic block's successors have to be specified before any of the
 278 instructions:
 279
 280 .. code-block:: text
 281
 282     bb.0.entry:
 283       successors: %bb.1.then, %bb.2.else
 284       <instructions>
 285     bb.1.then:
 286       <instructions>
 287     bb.2.else:
 288       <instructions>
 289
 290 The branch weights can be specified in brackets after the successor blocks.
 291 The example below defines a block that has two successors with branch weights
 292 of 32 and 16:
 293
 294 .. code-block:: text
 295
 296     bb.0.entry:
 297       successors: %bb.1.then(32), %bb.2.else(16)
 298
 299 .. _bb-liveins:
 300
 301 Live In Registers
 302 ^^^^^^^^^^^^^^^^^
 303
 304 The machine basic block's live in registers have to be specified before any of
 305 the instructions:
 306
 307 .. code-block:: text
 308
 309     bb.0.entry:
 310       liveins: $edi, $esi
 311
 312 The list of live in registers and successors can be empty. The language also
 313 allows multiple live in register and successor lists - they are combined into
 314 one list by the parser.
 315
 316 Miscellaneous Attributes
 317 ^^^^^^^^^^^^^^^^^^^^^^^^
 318
 319 The attributes ``IsAddressTaken``, ``IsLandingPad`` and ``Alignment`` can be
 320 specified in brackets after the block's definition:
 321
 322 .. code-block:: text
 323
 324     bb.0.entry (address-taken):
 325       <instructions>
 326     bb.2.else (align 4):
 327       <instructions>
 328     bb.3(landing-pad, align 4):
 329       <instructions>
 330
 331 .. TODO: Describe the way the reference to an unnamed LLVM IR block can be
 332    preserved.
 333
 334 Machine Instructions
 335 --------------------
 336
 337 A machine instruction is composed of a name,
 338 :ref:`machine operands <machine-operands>`,
 339 :ref:`instruction flags <instruction-flags>`, and machine memory operands.
 340
 341 The instruction's name is usually specified before the operands. The example
 342 below shows an instance of the X86 ``RETQ`` instruction with a single machine
 343 operand:
 344
 345 .. code-block:: text
 346
 347     RETQ $eax
 348
 349 However, if the machine instruction has one or more explicitly defined register
 350 operands, the instruction's name has to be specified after them. The example
 351 below shows an instance of the AArch64 ``LDPXpost`` instruction with three
 352 defined register operands:
 353
 354 .. code-block:: text
 355
 356     $sp, $fp, $lr = LDPXpost $sp, 2
 357
 358 The instruction names are serialized using the exact definitions from the
 359 target's ``*InstrInfo.td`` files, and they are case sensitive. This means that
 360 similar instruction names like ``TSTri`` and ``tSTRi`` represent different
 361 machine instructions.
 362
 363 .. _instruction-flags:
 364
 365 Instruction Flags
 366 ^^^^^^^^^^^^^^^^^
 367
 368 The flag ``frame-setup`` or ``frame-destroy`` can be specified before the
 369 instruction's name:
 370
 371 .. code-block:: text
 372
 373     $fp = frame-setup ADDXri $sp, 0, 0
 374
 375 .. code-block:: text
 376
 377     $x21, $x20 = frame-destroy LDPXi $sp
 378
 379 .. _registers:
 380
 381 Bundled Instructions
 382 ^^^^^^^^^^^^^^^^^^^^
 383
 384 The syntax for bundled instructions is the following:
 385
 386 .. code-block:: text
 387
 388     BUNDLE implicit-def $r0, implicit-def $r1, implicit $r2 {
 389       $r0 = SOME_OP $r2
 390       $r1 = ANOTHER_OP internal $r0
 391     }
 392
 393 The first instruction is often a bundle header. The instructions between ``{``
 394 and ``}`` are bundled with the first instruction.
 395
 396 Registers
 397 ---------
 398
 399 Registers are one of the key primitives in the machine instructions
 400 serialization language. They are primarily used in the
 401 :ref:`register machine operands <register-operands>`,
 402 but they can also be used in a number of other places, like the
 403 :ref:`basic block's live in list <bb-liveins>`.
 404
 405 The physical registers are identified by their name and by the '$' prefix sigil.
 406 They use the following syntax:
 407
 408 .. code-block:: text
 409
 410     $<name>
 411
 412 The example below shows three X86 physical registers:
 413
 414 .. code-block:: text
 415
 416     $eax
 417     $r15
 418     $eflags
 419
 420 The virtual registers are identified by their ID number and by the '%' sigil.
 421 They use the following syntax:
 422
 423 .. code-block:: text
 424
 425     %<id>
 426
 427 Example:
 428
 429 .. code-block:: text
 430
 431     %0
 432
 433 The null registers are represented using an underscore ('``_``'). They can also be
 434 represented using a '``$noreg``' named register, although the former syntax
 435 is preferred.
 436
 437 .. _machine-operands:
 438
 439 Machine Operands
 440 ----------------
 441
 442 There are seventeen different kinds of machine operands, and all of them can be
 443 serialized.
 444
 445 Immediate Operands
 446 ^^^^^^^^^^^^^^^^^^
 447
 448 The immediate machine operands are untyped, 64-bit signed integers. The
 449 example below shows an instance of the X86 ``MOV32ri`` instruction that has an
 450 immediate machine operand ``-42``:
 451
 452 .. code-block:: text
 453
 454     $eax = MOV32ri -42
 455
 456 An immediate operand is also used to represent a subregister index when the
 457 machine instruction has one of the following opcodes:
 458
 459 - ``EXTRACT_SUBREG``
 460
 461 - ``INSERT_SUBREG``
 462
 463 - ``REG_SEQUENCE``
 464
 465 - ``SUBREG_TO_REG``
 466
 467 In case this is true, the Machine Operand is printed according to the target.
 468
 469 For example:
 470
 471 In AArch64RegisterInfo.td:
 472
 473 .. code-block:: text
 474
 475   def sub_32 : SubRegIndex<32>;
 476
 477 If the third operand is an immediate with the value ``15`` (target-dependent
 478 value), based on the instruction's opcode and the operand's index the operand
 479 will be printed as ``%subreg.sub_32``:
 480
 481 .. code-block:: text
 482
 483     %1:gpr64 = SUBREG_TO_REG 0, %0, %subreg.sub_32
 484
 485 For integers > 64bit, we use a special machine operand, ``MO_CImmediate``,
 486 which stores the immediate in a ``ConstantInt`` using an ``APInt`` (LLVM's
 487 arbitrary precision integers).
 488
 489 .. TODO: Describe the FPIMM immediate operands.
 490
 491 .. _register-operands:
 492
 493 Register Operands
 494 ^^^^^^^^^^^^^^^^^
 495
 496 The :ref:`register <registers>` primitive is used to represent the register
 497 machine operands. The register operands can also have optional
 498 :ref:`register flags <register-flags>`,
 499 :ref:`a subregister index <subregister-indices>`,
 500 and a reference to the tied register operand.
 501 The full syntax of a register operand is shown below:
 502
 503 .. code-block:: text
 504
 505     [<flags>] <register> [ :<subregister-idx-name> ] [ (tied-def <tied-op>) ]
 506
 507 This example shows an instance of the X86 ``XOR32rr`` instruction that has
 508 5 register operands with different register flags:
 509
 510 .. code-block:: text
 511
 512   dead $eax = XOR32rr undef $eax, undef $eax, implicit-def dead $eflags, implicit-def $al
 513
 514 .. _register-flags:
 515
 516 Register Flags
 517 ~~~~~~~~~~~~~~
 518
 519 The table below shows all of the possible register flags along with the
 520 corresponding internal ``llvm::RegState`` representation:
 521
 522 .. list-table::
 523    :header-rows: 1
 524
 525    * - Flag
 526      - Internal Value
 527
 528    * - ``implicit``
 529      - ``RegState::Implicit``
 530
 531    * - ``implicit-def``
 532      - ``RegState::ImplicitDefine``
 533
 534    * - ``def``
 535      - ``RegState::Define``
 536
 537    * - ``dead``
 538      - ``RegState::Dead``
 539
 540    * - ``killed``
 541      - ``RegState::Kill``
 542
 543    * - ``undef``
 544      - ``RegState::Undef``
 545
 546    * - ``internal``
 547      - ``RegState::InternalRead``
 548
 549    * - ``early-clobber``
 550      - ``RegState::EarlyClobber``
 551
 552    * - ``debug-use``
 553      - ``RegState::Debug``
 554
 555    * - ``renamable``
 556      - ``RegState::Renamable``
 557
 558 .. _subregister-indices:
 559
 560 Subregister Indices
 561 ~~~~~~~~~~~~~~~~~~~
 562
 563 The register machine operands can reference a portion of a register by using
 564 the subregister indices. The example below shows an instance of the ``COPY``
 565 pseudo instruction that uses the X86 ``sub_8bit`` subregister index to copy 8
 566 lower bits from the 32-bit virtual register 0 to the 8-bit virtual register 1:
 567
 568 .. code-block:: text
 569
 570     %1 = COPY %0:sub_8bit
 571
 572 The names of the subregister indices are target specific, and are typically
 573 defined in the target's ``*RegisterInfo.td`` file.
 574
 575 Constant Pool Indices
 576 ^^^^^^^^^^^^^^^^^^^^^
 577
 578 A constant pool index (CPI) operand is printed using its index in the
 579 function's ``MachineConstantPool`` and an offset.
 580
 581 For example, a CPI with the index 1 and offset 8:
 582
 583 .. code-block:: text
 584
 585     %1:gr64 = MOV64ri %const.1 + 8
 586
 587 For a CPI with the index 0 and offset -12:
 588
 589 .. code-block:: text
 590
 591     %1:gr64 = MOV64ri %const.0 - 12
 592
 593 A constant pool entry is bound to a LLVM IR ``Constant`` or a target-specific
 594 ``MachineConstantPoolValue``. When serializing all the function's constants the
 595 following format is used:
 596
 597 .. code-block:: text
 598
 599     constants:
 600       - id:               <index>
 601         value:            <value>
 602         alignment:        <alignment>
 603         isTargetSpecific: <target-specific>
 604
 605 where ``<index>`` is a 32-bit unsigned integer, ``<value>`` is a `LLVM IR Constant
 606 <https://www.llvm.org/docs/LangRef.html#constants>`_, alignment is a 32-bit
 607 unsigned integer, and ``<target-specific>`` is either true or false.
 608
 609 Example:
 610
 611 .. code-block:: text
 612
 613     constants:
 614       - id:               0
 615         value:            'double 3.250000e+00'
 616         alignment:        8
 617       - id:               1
 618         value:            'g-(LPC0+8)'
 619         alignment:        4
 620         isTargetSpecific: true
 621
 622 Global Value Operands
 623 ^^^^^^^^^^^^^^^^^^^^^
 624
 625 The global value machine operands reference the global values from the
 626 :ref:`embedded LLVM IR module <embedded-module>`.
 627 The example below shows an instance of the X86 ``MOV64rm`` instruction that has
 628 a global value operand named ``G``:
 629
 630 .. code-block:: text
 631
 632     $rax = MOV64rm $rip, 1, _, @G, _
 633
 634 The named global values are represented using an identifier with the '@' prefix.
 635 If the identifier doesn't match the regular expression
 636 `[-a-zA-Z$._][-a-zA-Z$._0-9]*`, then this identifier must be quoted.
 637
 638 The unnamed global values are represented using an unsigned numeric value with
 639 the '@' prefix, like in the following examples: ``@0``, ``@989``.
 640
 641 Target-dependent Index Operands
 642 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 643
 644 A target index operand is a target-specific index and an offset. The
 645 target-specific index is printed using target-specific names and a positive or
 646 negative offset.
 647
 648 For example, the ``amdgpu-constdata-start`` is associated with the index ``0``
 649 in the AMDGPU backend. So if we have a target index operand with the index 0
 650 and the offset 8:
 651
 652 .. code-block:: text
 653
 654     $sgpr2 = S_ADD_U32 _, target-index(amdgpu-constdata-start) + 8, implicit-def _, implicit-def _
 655
 656 Jump-table Index Operands
 657 ^^^^^^^^^^^^^^^^^^^^^^^^^
 658
 659 A jump-table index operand with the index 0 is printed as following:
 660
 661 .. code-block:: text
 662
 663     tBR_JTr killed $r0, %jump-table.0
 664
 665 A machine jump-table entry contains a list of ``MachineBasicBlocks``. When serializing all the function's jump-table entries, the following format is used:
 666
 667 .. code-block:: text
 668
 669     jumpTable:
 670       kind:             <kind>
 671       entries:
 672         - id:             <index>
 673           blocks:         [ <bbreference>, <bbreference>, ... ]
 674
 675 where ``<kind>`` is describing how the jump table is represented and emitted (plain address, relocations, PIC, etc.), and each ``<index>`` is a 32-bit unsigned integer and ``blocks`` contains a list of :ref:`machine basic block references <block-references>`.
 676
 677 Example:
 678
 679 .. code-block:: text
 680
 681     jumpTable:
 682       kind:             inline
 683       entries:
 684         - id:             0
 685           blocks:         [ '%bb.3', '%bb.9', '%bb.4.d3' ]
 686         - id:             1
 687           blocks:         [ '%bb.7', '%bb.7', '%bb.4.d3', '%bb.5' ]
 688
 689 External Symbol Operands
 690 ^^^^^^^^^^^^^^^^^^^^^^^^^
 691
 692 An external symbol operand is represented using an identifier with the ``&``
 693 prefix. The identifier is surrounded with ""'s and escaped if it has any
 694 special non-printable characters in it.
 695
 696 Example:
 697
 698 .. code-block:: text
 699
 700     CALL64pcrel32 &__stack_chk_fail, csr_64, implicit $rsp, implicit-def $rsp
 701
 702 MCSymbol Operands
 703 ^^^^^^^^^^^^^^^^^
 704
 705 A MCSymbol operand is holding a pointer to a ``MCSymbol``. For the limitations
 706 of this operand in MIR, see :ref:`limitations <limitations>`.
 707
 708 The syntax is:
 709
 710 .. code-block:: text
 711
 712     EH_LABEL <mcsymbol Ltmp1>
 713
 714 CFIIndex Operands
 715 ^^^^^^^^^^^^^^^^^
 716
 717 A CFI Index operand is holding an index into a per-function side-table,
 718 ``MachineFunction::getFrameInstructions()``, which references all the frame
 719 instructions in a ``MachineFunction``. A ``CFI_INSTRUCTION`` may look like it
 720 contains multiple operands, but the only operand it contains is the CFI Index.
 721 The other operands are tracked by the ``MCCFIInstruction`` object.
 722
 723 The syntax is:
 724
 725 .. code-block:: text
 726
 727     CFI_INSTRUCTION offset $w30, -16
 728
 729 which may be emitted later in the MC layer as:
 730
 731 .. code-block:: text
 732
 733     .cfi_offset w30, -16
 734
 735 IntrinsicID Operands
 736 ^^^^^^^^^^^^^^^^^^^^
 737
 738 An Intrinsic ID operand contains a generic intrinsic ID or a target-specific ID.
 739
 740 The syntax for the ``returnaddress`` intrinsic is:
 741
 742 .. code-block:: text
 743
 744    $x0 = COPY intrinsic(@llvm.returnaddress)
 745
 746 Predicate Operands
 747 ^^^^^^^^^^^^^^^^^^
 748
 749 A Predicate operand contains an IR predicate from ``CmpInst::Predicate``, like
 750 ``ICMP_EQ``, etc.
 751
 752 For an int eq predicate ``ICMP_EQ``, the syntax is:
 753
 754 .. code-block:: text
 755
 756    %2:gpr(s32) = G_ICMP intpred(eq), %0, %1
 757
 758 .. TODO: Describe the parsers default behaviour when optional YAML attributes
 759    are missing.
 760 .. TODO: Describe the syntax for virtual register YAML definitions.
 761 .. TODO: Describe the machine function's YAML flag attributes.
 762 .. TODO: Describe the syntax for the register mask machine operands.
 763 .. TODO: Describe the frame information YAML mapping.
 764 .. TODO: Describe the syntax of the stack object machine operands and their
 765    YAML definitions.
 766 .. TODO: Describe the syntax of the block address machine operands.
 767 .. TODO: Describe the syntax of the metadata machine operands, and the
 768    instructions debug location attribute.
 769 .. TODO: Describe the syntax of the register live out machine operands.
 770 .. TODO: Describe the syntax of the machine memory operands.