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