1llvm-mca - LLVM Machine Code Analyzer 2===================================== 3 4.. program:: llvm-mca 5 6SYNOPSIS 7-------- 8 9:program:`llvm-mca` [*options*] [input] 10 11DESCRIPTION 12----------- 13 14:program:`llvm-mca` is a performance analysis tool that uses information 15available in LLVM (e.g. scheduling models) to statically measure the performance 16of machine code in a specific CPU. 17 18Performance is measured in terms of throughput as well as processor resource 19consumption. The tool currently works for processors with an out-of-order 20backend, for which there is a scheduling model available in LLVM. 21 22The main goal of this tool is not just to predict the performance of the code 23when run on the target, but also help with diagnosing potential performance 24issues. 25 26Given an assembly code sequence, :program:`llvm-mca` estimates the Instructions 27Per Cycle (IPC), as well as hardware resource pressure. The analysis and 28reporting style were inspired by the IACA tool from Intel. 29 30For example, you can compile code with clang, output assembly, and pipe it 31directly into :program:`llvm-mca` for analysis: 32 33.. code-block:: bash 34 35 $ clang foo.c -O2 -target x86_64-unknown-unknown -S -o - | llvm-mca -mcpu=btver2 36 37Or for Intel syntax: 38 39.. code-block:: bash 40 41 $ clang foo.c -O2 -target x86_64-unknown-unknown -mllvm -x86-asm-syntax=intel -S -o - | llvm-mca -mcpu=btver2 42 43Scheduling models are not just used to compute instruction latencies and 44throughput, but also to understand what processor resources are available 45and how to simulate them. 46 47By design, the quality of the analysis conducted by :program:`llvm-mca` is 48inevitably affected by the quality of the scheduling models in LLVM. 49 50If you see that the performance report is not accurate for a processor, 51please `file a bug <https://bugs.llvm.org/enter_bug.cgi?product=libraries>`_ 52against the appropriate backend. 53 54OPTIONS 55------- 56 57If ``input`` is "``-``" or omitted, :program:`llvm-mca` reads from standard 58input. Otherwise, it will read from the specified filename. 59 60If the :option:`-o` option is omitted, then :program:`llvm-mca` will send its output 61to standard output if the input is from standard input. If the :option:`-o` 62option specifies "``-``", then the output will also be sent to standard output. 63 64 65.. option:: -help 66 67 Print a summary of command line options. 68 69.. option:: -o <filename> 70 71 Use ``<filename>`` as the output filename. See the summary above for more 72 details. 73 74.. option:: -mtriple=<target triple> 75 76 Specify a target triple string. 77 78.. option:: -march=<arch> 79 80 Specify the architecture for which to analyze the code. It defaults to the 81 host default target. 82 83.. option:: -mcpu=<cpuname> 84 85 Specify the processor for which to analyze the code. By default, the cpu name 86 is autodetected from the host. 87 88.. option:: -output-asm-variant=<variant id> 89 90 Specify the output assembly variant for the report generated by the tool. 91 On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables 92 the AT&T (vic. Intel) assembly format for the code printed out by the tool in 93 the analysis report. 94 95.. option:: -print-imm-hex 96 97 Prefer hex format for numeric literals in the output assembly printed as part 98 of the report. 99 100.. option:: -dispatch=<width> 101 102 Specify a different dispatch width for the processor. The dispatch width 103 defaults to field 'IssueWidth' in the processor scheduling model. If width is 104 zero, then the default dispatch width is used. 105 106.. option:: -register-file-size=<size> 107 108 Specify the size of the register file. When specified, this flag limits how 109 many physical registers are available for register renaming purposes. A value 110 of zero for this flag means "unlimited number of physical registers". 111 112.. option:: -iterations=<number of iterations> 113 114 Specify the number of iterations to run. If this flag is set to 0, then the 115 tool sets the number of iterations to a default value (i.e. 100). 116 117.. option:: -noalias=<bool> 118 119 If set, the tool assumes that loads and stores don't alias. This is the 120 default behavior. 121 122.. option:: -lqueue=<load queue size> 123 124 Specify the size of the load queue in the load/store unit emulated by the tool. 125 By default, the tool assumes an unbound number of entries in the load queue. 126 A value of zero for this flag is ignored, and the default load queue size is 127 used instead. 128 129.. option:: -squeue=<store queue size> 130 131 Specify the size of the store queue in the load/store unit emulated by the 132 tool. By default, the tool assumes an unbound number of entries in the store 133 queue. A value of zero for this flag is ignored, and the default store queue 134 size is used instead. 135 136.. option:: -timeline 137 138 Enable the timeline view. 139 140.. option:: -timeline-max-iterations=<iterations> 141 142 Limit the number of iterations to print in the timeline view. By default, the 143 timeline view prints information for up to 10 iterations. 144 145.. option:: -timeline-max-cycles=<cycles> 146 147 Limit the number of cycles in the timeline view. By default, the number of 148 cycles is set to 80. 149 150.. option:: -resource-pressure 151 152 Enable the resource pressure view. This is enabled by default. 153 154.. option:: -register-file-stats 155 156 Enable register file usage statistics. 157 158.. option:: -dispatch-stats 159 160 Enable extra dispatch statistics. This view collects and analyzes instruction 161 dispatch events, as well as static/dynamic dispatch stall events. This view 162 is disabled by default. 163 164.. option:: -scheduler-stats 165 166 Enable extra scheduler statistics. This view collects and analyzes instruction 167 issue events. This view is disabled by default. 168 169.. option:: -retire-stats 170 171 Enable extra retire control unit statistics. This view is disabled by default. 172 173.. option:: -instruction-info 174 175 Enable the instruction info view. This is enabled by default. 176 177.. option:: -show-encoding 178 179 Enable the printing of instruction encodings within the instruction info view. 180 181.. option:: -all-stats 182 183 Print all hardware statistics. This enables extra statistics related to the 184 dispatch logic, the hardware schedulers, the register file(s), and the retire 185 control unit. This option is disabled by default. 186 187.. option:: -all-views 188 189 Enable all the view. 190 191.. option:: -instruction-tables 192 193 Prints resource pressure information based on the static information 194 available from the processor model. This differs from the resource pressure 195 view because it doesn't require that the code is simulated. It instead prints 196 the theoretical uniform distribution of resource pressure for every 197 instruction in sequence. 198 199.. option:: -bottleneck-analysis 200 201 Print information about bottlenecks that affect the throughput. This analysis 202 can be expensive, and it is disabled by default. Bottlenecks are highlighted 203 in the summary view. 204 205 206EXIT STATUS 207----------- 208 209:program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed 210to standard error, and the tool returns 1. 211 212USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS 213--------------------------------------------- 214:program:`llvm-mca` allows for the optional usage of special code comments to 215mark regions of the assembly code to be analyzed. A comment starting with 216substring ``LLVM-MCA-BEGIN`` marks the beginning of a code region. A comment 217starting with substring ``LLVM-MCA-END`` marks the end of a code region. For 218example: 219 220.. code-block:: none 221 222 # LLVM-MCA-BEGIN 223 ... 224 # LLVM-MCA-END 225 226If no user-defined region is specified, then :program:`llvm-mca` assumes a 227default region which contains every instruction in the input file. Every region 228is analyzed in isolation, and the final performance report is the union of all 229the reports generated for every code region. 230 231Code regions can have names. For example: 232 233.. code-block:: none 234 235 # LLVM-MCA-BEGIN A simple example 236 add %eax, %eax 237 # LLVM-MCA-END 238 239The code from the example above defines a region named "A simple example" with a 240single instruction in it. Note how the region name doesn't have to be repeated 241in the ``LLVM-MCA-END`` directive. In the absence of overlapping regions, 242an anonymous ``LLVM-MCA-END`` directive always ends the currently active user 243defined region. 244 245Example of nesting regions: 246 247.. code-block:: none 248 249 # LLVM-MCA-BEGIN foo 250 add %eax, %edx 251 # LLVM-MCA-BEGIN bar 252 sub %eax, %edx 253 # LLVM-MCA-END bar 254 # LLVM-MCA-END foo 255 256Example of overlapping regions: 257 258.. code-block:: none 259 260 # LLVM-MCA-BEGIN foo 261 add %eax, %edx 262 # LLVM-MCA-BEGIN bar 263 sub %eax, %edx 264 # LLVM-MCA-END foo 265 add %eax, %edx 266 # LLVM-MCA-END bar 267 268Note that multiple anonymous regions cannot overlap. Also, overlapping regions 269cannot have the same name. 270 271There is no support for marking regions from high-level source code, like C or 272C++. As a workaround, inline assembly directives may be used: 273 274.. code-block:: c++ 275 276 int foo(int a, int b) { 277 __asm volatile("# LLVM-MCA-BEGIN foo"); 278 a += 42; 279 __asm volatile("# LLVM-MCA-END"); 280 a *= b; 281 return a; 282 } 283 284However, this interferes with optimizations like loop vectorization and may have 285an impact on the code generated. This is because the ``__asm`` statements are 286seen as real code having important side effects, which limits how the code 287around them can be transformed. If users want to make use of inline assembly 288to emit markers, then the recommendation is to always verify that the output 289assembly is equivalent to the assembly generated in the absence of markers. 290The `Clang options to emit optimization reports <https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports>`_ 291can also help in detecting missed optimizations. 292 293HOW LLVM-MCA WORKS 294------------------ 295 296:program:`llvm-mca` takes assembly code as input. The assembly code is parsed 297into a sequence of MCInst with the help of the existing LLVM target assembly 298parsers. The parsed sequence of MCInst is then analyzed by a ``Pipeline`` module 299to generate a performance report. 300 301The Pipeline module simulates the execution of the machine code sequence in a 302loop of iterations (default is 100). During this process, the pipeline collects 303a number of execution related statistics. At the end of this process, the 304pipeline generates and prints a report from the collected statistics. 305 306Here is an example of a performance report generated by the tool for a 307dot-product of two packed float vectors of four elements. The analysis is 308conducted for target x86, cpu btver2. The following result can be produced via 309the following command using the example located at 310``test/tools/llvm-mca/X86/BtVer2/dot-product.s``: 311 312.. code-block:: bash 313 314 $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=300 dot-product.s 315 316.. code-block:: none 317 318 Iterations: 300 319 Instructions: 900 320 Total Cycles: 610 321 Total uOps: 900 322 323 Dispatch Width: 2 324 uOps Per Cycle: 1.48 325 IPC: 1.48 326 Block RThroughput: 2.0 327 328 329 Instruction Info: 330 [1]: #uOps 331 [2]: Latency 332 [3]: RThroughput 333 [4]: MayLoad 334 [5]: MayStore 335 [6]: HasSideEffects (U) 336 337 [1] [2] [3] [4] [5] [6] Instructions: 338 1 2 1.00 vmulps %xmm0, %xmm1, %xmm2 339 1 3 1.00 vhaddps %xmm2, %xmm2, %xmm3 340 1 3 1.00 vhaddps %xmm3, %xmm3, %xmm4 341 342 343 Resources: 344 [0] - JALU0 345 [1] - JALU1 346 [2] - JDiv 347 [3] - JFPA 348 [4] - JFPM 349 [5] - JFPU0 350 [6] - JFPU1 351 [7] - JLAGU 352 [8] - JMul 353 [9] - JSAGU 354 [10] - JSTC 355 [11] - JVALU0 356 [12] - JVALU1 357 [13] - JVIMUL 358 359 360 Resource pressure per iteration: 361 [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] 362 - - - 2.00 1.00 2.00 1.00 - - - - - - - 363 364 Resource pressure by instruction: 365 [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] Instructions: 366 - - - - 1.00 - 1.00 - - - - - - - vmulps %xmm0, %xmm1, %xmm2 367 - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm2, %xmm2, %xmm3 368 - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm3, %xmm3, %xmm4 369 370According to this report, the dot-product kernel has been executed 300 times, 371for a total of 900 simulated instructions. The total number of simulated micro 372opcodes (uOps) is also 900. 373 374The report is structured in three main sections. The first section collects a 375few performance numbers; the goal of this section is to give a very quick 376overview of the performance throughput. Important performance indicators are 377**IPC**, **uOps Per Cycle**, and **Block RThroughput** (Block Reciprocal 378Throughput). 379 380Field *DispatchWidth* is the maximum number of micro opcodes that are dispatched 381to the out-of-order backend every simulated cycle. 382 383IPC is computed dividing the total number of simulated instructions by the total 384number of cycles. 385 386Field *Block RThroughput* is the reciprocal of the block throughput. Block 387throuhgput is a theoretical quantity computed as the maximum number of blocks 388(i.e. iterations) that can be executed per simulated clock cycle in the absence 389of loop carried dependencies. Block throughput is is superiorly 390limited by the dispatch rate, and the availability of hardware resources. 391 392In the absence of loop-carried data dependencies, the observed IPC tends to a 393theoretical maximum which can be computed by dividing the number of instructions 394of a single iteration by the `Block RThroughput`. 395 396Field 'uOps Per Cycle' is computed dividing the total number of simulated micro 397opcodes by the total number of cycles. A delta between Dispatch Width and this 398field is an indicator of a performance issue. In the absence of loop-carried 399data dependencies, the observed 'uOps Per Cycle' should tend to a theoretical 400maximum throughput which can be computed by dividing the number of uOps of a 401single iteration by the `Block RThroughput`. 402 403Field *uOps Per Cycle* is bounded from above by the dispatch width. That is 404because the dispatch width limits the maximum size of a dispatch group. Both IPC 405and 'uOps Per Cycle' are limited by the amount of hardware parallelism. The 406availability of hardware resources affects the resource pressure distribution, 407and it limits the number of instructions that can be executed in parallel every 408cycle. A delta between Dispatch Width and the theoretical maximum uOps per 409Cycle (computed by dividing the number of uOps of a single iteration by the 410`Block RThroughput`) is an indicator of a performance bottleneck caused by the 411lack of hardware resources. 412In general, the lower the Block RThroughput, the better. 413 414In this example, ``uOps per iteration/Block RThroughput`` is 1.50. Since there 415are no loop-carried dependencies, the observed `uOps Per Cycle` is expected to 416approach 1.50 when the number of iterations tends to infinity. The delta between 417the Dispatch Width (2.00), and the theoretical maximum uOp throughput (1.50) is 418an indicator of a performance bottleneck caused by the lack of hardware 419resources, and the *Resource pressure view* can help to identify the problematic 420resource usage. 421 422The second section of the report is the `instruction info view`. It shows the 423latency and reciprocal throughput of every instruction in the sequence. It also 424reports extra information related to the number of micro opcodes, and opcode 425properties (i.e., 'MayLoad', 'MayStore', and 'HasSideEffects'). 426 427Field *RThroughput* is the reciprocal of the instruction throughput. Throughput 428is computed as the maximum number of instructions of a same type that can be 429executed per clock cycle in the absence of operand dependencies. In this 430example, the reciprocal throughput of a vector float multiply is 1 431cycles/instruction. That is because the FP multiplier JFPM is only available 432from pipeline JFPU1. 433 434Instruction encodings are displayed within the instruction info view when flag 435`-show-encoding` is specified. 436 437Below is an example of `-show-encoding` output for the dot-product kernel: 438 439.. code-block:: none 440 441 Instruction Info: 442 [1]: #uOps 443 [2]: Latency 444 [3]: RThroughput 445 [4]: MayLoad 446 [5]: MayStore 447 [6]: HasSideEffects (U) 448 [7]: Encoding Size 449 450 [1] [2] [3] [4] [5] [6] [7] Encodings: Instructions: 451 1 2 1.00 4 c5 f0 59 d0 vmulps %xmm0, %xmm1, %xmm2 452 1 4 1.00 4 c5 eb 7c da vhaddps %xmm2, %xmm2, %xmm3 453 1 4 1.00 4 c5 e3 7c e3 vhaddps %xmm3, %xmm3, %xmm4 454 455The `Encoding Size` column shows the size in bytes of instructions. The 456`Encodings` column shows the actual instruction encodings (byte sequences in 457hex). 458 459The third section is the *Resource pressure view*. This view reports 460the average number of resource cycles consumed every iteration by instructions 461for every processor resource unit available on the target. Information is 462structured in two tables. The first table reports the number of resource cycles 463spent on average every iteration. The second table correlates the resource 464cycles to the machine instruction in the sequence. For example, every iteration 465of the instruction vmulps always executes on resource unit [6] 466(JFPU1 - floating point pipeline #1), consuming an average of 1 resource cycle 467per iteration. Note that on AMD Jaguar, vector floating-point multiply can 468only be issued to pipeline JFPU1, while horizontal floating-point additions can 469only be issued to pipeline JFPU0. 470 471The resource pressure view helps with identifying bottlenecks caused by high 472usage of specific hardware resources. Situations with resource pressure mainly 473concentrated on a few resources should, in general, be avoided. Ideally, 474pressure should be uniformly distributed between multiple resources. 475 476Timeline View 477^^^^^^^^^^^^^ 478The timeline view produces a detailed report of each instruction's state 479transitions through an instruction pipeline. This view is enabled by the 480command line option ``-timeline``. As instructions transition through the 481various stages of the pipeline, their states are depicted in the view report. 482These states are represented by the following characters: 483 484* D : Instruction dispatched. 485* e : Instruction executing. 486* E : Instruction executed. 487* R : Instruction retired. 488* = : Instruction already dispatched, waiting to be executed. 489* \- : Instruction executed, waiting to be retired. 490 491Below is the timeline view for a subset of the dot-product example located in 492``test/tools/llvm-mca/X86/BtVer2/dot-product.s`` and processed by 493:program:`llvm-mca` using the following command: 494 495.. code-block:: bash 496 497 $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=3 -timeline dot-product.s 498 499.. code-block:: none 500 501 Timeline view: 502 012345 503 Index 0123456789 504 505 [0,0] DeeER. . . vmulps %xmm0, %xmm1, %xmm2 506 [0,1] D==eeeER . . vhaddps %xmm2, %xmm2, %xmm3 507 [0,2] .D====eeeER . vhaddps %xmm3, %xmm3, %xmm4 508 [1,0] .DeeE-----R . vmulps %xmm0, %xmm1, %xmm2 509 [1,1] . D=eeeE---R . vhaddps %xmm2, %xmm2, %xmm3 510 [1,2] . D====eeeER . vhaddps %xmm3, %xmm3, %xmm4 511 [2,0] . DeeE-----R . vmulps %xmm0, %xmm1, %xmm2 512 [2,1] . D====eeeER . vhaddps %xmm2, %xmm2, %xmm3 513 [2,2] . D======eeeER vhaddps %xmm3, %xmm3, %xmm4 514 515 516 Average Wait times (based on the timeline view): 517 [0]: Executions 518 [1]: Average time spent waiting in a scheduler's queue 519 [2]: Average time spent waiting in a scheduler's queue while ready 520 [3]: Average time elapsed from WB until retire stage 521 522 [0] [1] [2] [3] 523 0. 3 1.0 1.0 3.3 vmulps %xmm0, %xmm1, %xmm2 524 1. 3 3.3 0.7 1.0 vhaddps %xmm2, %xmm2, %xmm3 525 2. 3 5.7 0.0 0.0 vhaddps %xmm3, %xmm3, %xmm4 526 3 3.3 0.5 1.4 <total> 527 528The timeline view is interesting because it shows instruction state changes 529during execution. It also gives an idea of how the tool processes instructions 530executed on the target, and how their timing information might be calculated. 531 532The timeline view is structured in two tables. The first table shows 533instructions changing state over time (measured in cycles); the second table 534(named *Average Wait times*) reports useful timing statistics, which should 535help diagnose performance bottlenecks caused by long data dependencies and 536sub-optimal usage of hardware resources. 537 538An instruction in the timeline view is identified by a pair of indices, where 539the first index identifies an iteration, and the second index is the 540instruction index (i.e., where it appears in the code sequence). Since this 541example was generated using 3 iterations: ``-iterations=3``, the iteration 542indices range from 0-2 inclusively. 543 544Excluding the first and last column, the remaining columns are in cycles. 545Cycles are numbered sequentially starting from 0. 546 547From the example output above, we know the following: 548 549* Instruction [1,0] was dispatched at cycle 1. 550* Instruction [1,0] started executing at cycle 2. 551* Instruction [1,0] reached the write back stage at cycle 4. 552* Instruction [1,0] was retired at cycle 10. 553 554Instruction [1,0] (i.e., vmulps from iteration #1) does not have to wait in the 555scheduler's queue for the operands to become available. By the time vmulps is 556dispatched, operands are already available, and pipeline JFPU1 is ready to 557serve another instruction. So the instruction can be immediately issued on the 558JFPU1 pipeline. That is demonstrated by the fact that the instruction only 559spent 1cy in the scheduler's queue. 560 561There is a gap of 5 cycles between the write-back stage and the retire event. 562That is because instructions must retire in program order, so [1,0] has to wait 563for [0,2] to be retired first (i.e., it has to wait until cycle 10). 564 565In the example, all instructions are in a RAW (Read After Write) dependency 566chain. Register %xmm2 written by vmulps is immediately used by the first 567vhaddps, and register %xmm3 written by the first vhaddps is used by the second 568vhaddps. Long data dependencies negatively impact the ILP (Instruction Level 569Parallelism). 570 571In the dot-product example, there are anti-dependencies introduced by 572instructions from different iterations. However, those dependencies can be 573removed at register renaming stage (at the cost of allocating register aliases, 574and therefore consuming physical registers). 575 576Table *Average Wait times* helps diagnose performance issues that are caused by 577the presence of long latency instructions and potentially long data dependencies 578which may limit the ILP. Last row, ``<total>``, shows a global average over all 579instructions measured. Note that :program:`llvm-mca`, by default, assumes at 580least 1cy between the dispatch event and the issue event. 581 582When the performance is limited by data dependencies and/or long latency 583instructions, the number of cycles spent while in the *ready* state is expected 584to be very small when compared with the total number of cycles spent in the 585scheduler's queue. The difference between the two counters is a good indicator 586of how large of an impact data dependencies had on the execution of the 587instructions. When performance is mostly limited by the lack of hardware 588resources, the delta between the two counters is small. However, the number of 589cycles spent in the queue tends to be larger (i.e., more than 1-3cy), 590especially when compared to other low latency instructions. 591 592Bottleneck Analysis 593^^^^^^^^^^^^^^^^^^^ 594The ``-bottleneck-analysis`` command line option enables the analysis of 595performance bottlenecks. 596 597This analysis is potentially expensive. It attempts to correlate increases in 598backend pressure (caused by pipeline resource pressure and data dependencies) to 599dynamic dispatch stalls. 600 601Below is an example of ``-bottleneck-analysis`` output generated by 602:program:`llvm-mca` for 500 iterations of the dot-product example on btver2. 603 604.. code-block:: none 605 606 607 Cycles with backend pressure increase [ 48.07% ] 608 Throughput Bottlenecks: 609 Resource Pressure [ 47.77% ] 610 - JFPA [ 47.77% ] 611 - JFPU0 [ 47.77% ] 612 Data Dependencies: [ 0.30% ] 613 - Register Dependencies [ 0.30% ] 614 - Memory Dependencies [ 0.00% ] 615 616 Critical sequence based on the simulation: 617 618 Instruction Dependency Information 619 +----< 2. vhaddps %xmm3, %xmm3, %xmm4 620 | 621 | < loop carried > 622 | 623 | 0. vmulps %xmm0, %xmm1, %xmm2 624 +----> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ] 625 +----> 2. vhaddps %xmm3, %xmm3, %xmm4 ## REGISTER dependency: %xmm3 626 | 627 | < loop carried > 628 | 629 +----> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ] 630 631 632According to the analysis, throughput is limited by resource pressure and not by 633data dependencies. The analysis observed increases in backend pressure during 63448.07% of the simulated run. Almost all those pressure increase events were 635caused by contention on processor resources JFPA/JFPU0. 636 637The `critical sequence` is the most expensive sequence of instructions according 638to the simulation. It is annotated to provide extra information about critical 639register dependencies and resource interferences between instructions. 640 641Instructions from the critical sequence are expected to significantly impact 642performance. By construction, the accuracy of this analysis is strongly 643dependent on the simulation and (as always) by the quality of the processor 644model in llvm. 645 646 647Extra Statistics to Further Diagnose Performance Issues 648^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 649The ``-all-stats`` command line option enables extra statistics and performance 650counters for the dispatch logic, the reorder buffer, the retire control unit, 651and the register file. 652 653Below is an example of ``-all-stats`` output generated by :program:`llvm-mca` 654for 300 iterations of the dot-product example discussed in the previous 655sections. 656 657.. code-block:: none 658 659 Dynamic Dispatch Stall Cycles: 660 RAT - Register unavailable: 0 661 RCU - Retire tokens unavailable: 0 662 SCHEDQ - Scheduler full: 272 (44.6%) 663 LQ - Load queue full: 0 664 SQ - Store queue full: 0 665 GROUP - Static restrictions on the dispatch group: 0 666 667 668 Dispatch Logic - number of cycles where we saw N micro opcodes dispatched: 669 [# dispatched], [# cycles] 670 0, 24 (3.9%) 671 1, 272 (44.6%) 672 2, 314 (51.5%) 673 674 675 Schedulers - number of cycles where we saw N micro opcodes issued: 676 [# issued], [# cycles] 677 0, 7 (1.1%) 678 1, 306 (50.2%) 679 2, 297 (48.7%) 680 681 Scheduler's queue usage: 682 [1] Resource name. 683 [2] Average number of used buffer entries. 684 [3] Maximum number of used buffer entries. 685 [4] Total number of buffer entries. 686 687 [1] [2] [3] [4] 688 JALU01 0 0 20 689 JFPU01 17 18 18 690 JLSAGU 0 0 12 691 692 693 Retire Control Unit - number of cycles where we saw N instructions retired: 694 [# retired], [# cycles] 695 0, 109 (17.9%) 696 1, 102 (16.7%) 697 2, 399 (65.4%) 698 699 Total ROB Entries: 64 700 Max Used ROB Entries: 35 ( 54.7% ) 701 Average Used ROB Entries per cy: 32 ( 50.0% ) 702 703 704 Register File statistics: 705 Total number of mappings created: 900 706 Max number of mappings used: 35 707 708 * Register File #1 -- JFpuPRF: 709 Number of physical registers: 72 710 Total number of mappings created: 900 711 Max number of mappings used: 35 712 713 * Register File #2 -- JIntegerPRF: 714 Number of physical registers: 64 715 Total number of mappings created: 0 716 Max number of mappings used: 0 717 718If we look at the *Dynamic Dispatch Stall Cycles* table, we see the counter for 719SCHEDQ reports 272 cycles. This counter is incremented every time the dispatch 720logic is unable to dispatch a full group because the scheduler's queue is full. 721 722Looking at the *Dispatch Logic* table, we see that the pipeline was only able to 723dispatch two micro opcodes 51.5% of the time. The dispatch group was limited to 724one micro opcode 44.6% of the cycles, which corresponds to 272 cycles. The 725dispatch statistics are displayed by either using the command option 726``-all-stats`` or ``-dispatch-stats``. 727 728The next table, *Schedulers*, presents a histogram displaying a count, 729representing the number of micro opcodes issued on some number of cycles. In 730this case, of the 610 simulated cycles, single opcodes were issued 306 times 731(50.2%) and there were 7 cycles where no opcodes were issued. 732 733The *Scheduler's queue usage* table shows that the average and maximum number of 734buffer entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01 735reached its maximum (18 of 18 queue entries). Note that AMD Jaguar implements 736three schedulers: 737 738* JALU01 - A scheduler for ALU instructions. 739* JFPU01 - A scheduler floating point operations. 740* JLSAGU - A scheduler for address generation. 741 742The dot-product is a kernel of three floating point instructions (a vector 743multiply followed by two horizontal adds). That explains why only the floating 744point scheduler appears to be used. 745 746A full scheduler queue is either caused by data dependency chains or by a 747sub-optimal usage of hardware resources. Sometimes, resource pressure can be 748mitigated by rewriting the kernel using different instructions that consume 749different scheduler resources. Schedulers with a small queue are less resilient 750to bottlenecks caused by the presence of long data dependencies. The scheduler 751statistics are displayed by using the command option ``-all-stats`` or 752``-scheduler-stats``. 753 754The next table, *Retire Control Unit*, presents a histogram displaying a count, 755representing the number of instructions retired on some number of cycles. In 756this case, of the 610 simulated cycles, two instructions were retired during the 757same cycle 399 times (65.4%) and there were 109 cycles where no instructions 758were retired. The retire statistics are displayed by using the command option 759``-all-stats`` or ``-retire-stats``. 760 761The last table presented is *Register File statistics*. Each physical register 762file (PRF) used by the pipeline is presented in this table. In the case of AMD 763Jaguar, there are two register files, one for floating-point registers (JFpuPRF) 764and one for integer registers (JIntegerPRF). The table shows that of the 900 765instructions processed, there were 900 mappings created. Since this dot-product 766example utilized only floating point registers, the JFPuPRF was responsible for 767creating the 900 mappings. However, we see that the pipeline only used a 768maximum of 35 of 72 available register slots at any given time. We can conclude 769that the floating point PRF was the only register file used for the example, and 770that it was never resource constrained. The register file statistics are 771displayed by using the command option ``-all-stats`` or 772``-register-file-stats``. 773 774In this example, we can conclude that the IPC is mostly limited by data 775dependencies, and not by resource pressure. 776 777Instruction Flow 778^^^^^^^^^^^^^^^^ 779This section describes the instruction flow through the default pipeline of 780:program:`llvm-mca`, as well as the functional units involved in the process. 781 782The default pipeline implements the following sequence of stages used to 783process instructions. 784 785* Dispatch (Instruction is dispatched to the schedulers). 786* Issue (Instruction is issued to the processor pipelines). 787* Write Back (Instruction is executed, and results are written back). 788* Retire (Instruction is retired; writes are architecturally committed). 789 790The default pipeline only models the out-of-order portion of a processor. 791Therefore, the instruction fetch and decode stages are not modeled. Performance 792bottlenecks in the frontend are not diagnosed. :program:`llvm-mca` assumes that 793instructions have all been decoded and placed into a queue before the simulation 794start. Also, :program:`llvm-mca` does not model branch prediction. 795 796Instruction Dispatch 797"""""""""""""""""""" 798During the dispatch stage, instructions are picked in program order from a 799queue of already decoded instructions, and dispatched in groups to the 800simulated hardware schedulers. 801 802The size of a dispatch group depends on the availability of the simulated 803hardware resources. The processor dispatch width defaults to the value 804of the ``IssueWidth`` in LLVM's scheduling model. 805 806An instruction can be dispatched if: 807 808* The size of the dispatch group is smaller than processor's dispatch width. 809* There are enough entries in the reorder buffer. 810* There are enough physical registers to do register renaming. 811* The schedulers are not full. 812 813Scheduling models can optionally specify which register files are available on 814the processor. :program:`llvm-mca` uses that information to initialize register 815file descriptors. Users can limit the number of physical registers that are 816globally available for register renaming by using the command option 817``-register-file-size``. A value of zero for this option means *unbounded*. By 818knowing how many registers are available for renaming, the tool can predict 819dispatch stalls caused by the lack of physical registers. 820 821The number of reorder buffer entries consumed by an instruction depends on the 822number of micro-opcodes specified for that instruction by the target scheduling 823model. The reorder buffer is responsible for tracking the progress of 824instructions that are "in-flight", and retiring them in program order. The 825number of entries in the reorder buffer defaults to the value specified by field 826`MicroOpBufferSize` in the target scheduling model. 827 828Instructions that are dispatched to the schedulers consume scheduler buffer 829entries. :program:`llvm-mca` queries the scheduling model to determine the set 830of buffered resources consumed by an instruction. Buffered resources are 831treated like scheduler resources. 832 833Instruction Issue 834""""""""""""""""" 835Each processor scheduler implements a buffer of instructions. An instruction 836has to wait in the scheduler's buffer until input register operands become 837available. Only at that point, does the instruction becomes eligible for 838execution and may be issued (potentially out-of-order) for execution. 839Instruction latencies are computed by :program:`llvm-mca` with the help of the 840scheduling model. 841 842:program:`llvm-mca`'s scheduler is designed to simulate multiple processor 843schedulers. The scheduler is responsible for tracking data dependencies, and 844dynamically selecting which processor resources are consumed by instructions. 845It delegates the management of processor resource units and resource groups to a 846resource manager. The resource manager is responsible for selecting resource 847units that are consumed by instructions. For example, if an instruction 848consumes 1cy of a resource group, the resource manager selects one of the 849available units from the group; by default, the resource manager uses a 850round-robin selector to guarantee that resource usage is uniformly distributed 851between all units of a group. 852 853:program:`llvm-mca`'s scheduler internally groups instructions into three sets: 854 855* WaitSet: a set of instructions whose operands are not ready. 856* ReadySet: a set of instructions ready to execute. 857* IssuedSet: a set of instructions executing. 858 859Depending on the operands availability, instructions that are dispatched to the 860scheduler are either placed into the WaitSet or into the ReadySet. 861 862Every cycle, the scheduler checks if instructions can be moved from the WaitSet 863to the ReadySet, and if instructions from the ReadySet can be issued to the 864underlying pipelines. The algorithm prioritizes older instructions over younger 865instructions. 866 867Write-Back and Retire Stage 868""""""""""""""""""""""""""" 869Issued instructions are moved from the ReadySet to the IssuedSet. There, 870instructions wait until they reach the write-back stage. At that point, they 871get removed from the queue and the retire control unit is notified. 872 873When instructions are executed, the retire control unit flags the instruction as 874"ready to retire." 875 876Instructions are retired in program order. The register file is notified of the 877retirement so that it can free the physical registers that were allocated for 878the instruction during the register renaming stage. 879 880Load/Store Unit and Memory Consistency Model 881"""""""""""""""""""""""""""""""""""""""""""" 882To simulate an out-of-order execution of memory operations, :program:`llvm-mca` 883utilizes a simulated load/store unit (LSUnit) to simulate the speculative 884execution of loads and stores. 885 886Each load (or store) consumes an entry in the load (or store) queue. Users can 887specify flags ``-lqueue`` and ``-squeue`` to limit the number of entries in the 888load and store queues respectively. The queues are unbounded by default. 889 890The LSUnit implements a relaxed consistency model for memory loads and stores. 891The rules are: 892 8931. A younger load is allowed to pass an older load only if there are no 894 intervening stores or barriers between the two loads. 8952. A younger load is allowed to pass an older store provided that the load does 896 not alias with the store. 8973. A younger store is not allowed to pass an older store. 8984. A younger store is not allowed to pass an older load. 899 900By default, the LSUnit optimistically assumes that loads do not alias 901(`-noalias=true`) store operations. Under this assumption, younger loads are 902always allowed to pass older stores. Essentially, the LSUnit does not attempt 903to run any alias analysis to predict when loads and stores do not alias with 904each other. 905 906Note that, in the case of write-combining memory, rule 3 could be relaxed to 907allow reordering of non-aliasing store operations. That being said, at the 908moment, there is no way to further relax the memory model (``-noalias`` is the 909only option). Essentially, there is no option to specify a different memory 910type (e.g., write-back, write-combining, write-through; etc.) and consequently 911to weaken, or strengthen, the memory model. 912 913Other limitations are: 914 915* The LSUnit does not know when store-to-load forwarding may occur. 916* The LSUnit does not know anything about cache hierarchy and memory types. 917* The LSUnit does not know how to identify serializing operations and memory 918 fences. 919 920The LSUnit does not attempt to predict if a load or store hits or misses the L1 921cache. It only knows if an instruction "MayLoad" and/or "MayStore." For 922loads, the scheduling model provides an "optimistic" load-to-use latency (which 923usually matches the load-to-use latency for when there is a hit in the L1D). 924 925:program:`llvm-mca` does not know about serializing operations or memory-barrier 926like instructions. The LSUnit conservatively assumes that an instruction which 927has both "MayLoad" and unmodeled side effects behaves like a "soft" 928load-barrier. That means, it serializes loads without forcing a flush of the 929load queue. Similarly, instructions that "MayStore" and have unmodeled side 930effects are treated like store barriers. A full memory barrier is a "MayLoad" 931and "MayStore" instruction with unmodeled side effects. This is inaccurate, but 932it is the best that we can do at the moment with the current information 933available in LLVM. 934 935A load/store barrier consumes one entry of the load/store queue. A load/store 936barrier enforces ordering of loads/stores. A younger load cannot pass a load 937barrier. Also, a younger store cannot pass a store barrier. A younger load 938has to wait for the memory/load barrier to execute. A load/store barrier is 939"executed" when it becomes the oldest entry in the load/store queue(s). That 940also means, by construction, all of the older loads/stores have been executed. 941 942In conclusion, the full set of load/store consistency rules are: 943 944#. A store may not pass a previous store. 945#. A store may not pass a previous load (regardless of ``-noalias``). 946#. A store has to wait until an older store barrier is fully executed. 947#. A load may pass a previous load. 948#. A load may not pass a previous store unless ``-noalias`` is set. 949#. A load has to wait until an older load barrier is fully executed. 950