1llvm-mca - LLVM Machine Code Analyzer
2=====================================
3
4SYNOPSIS
5--------
6
7:program:`llvm-mca` [*options*] [input]
8
9DESCRIPTION
10-----------
11
12:program:`llvm-mca` is a performance analysis tool that uses information
13available in LLVM (e.g. scheduling models) to statically measure the performance
14of machine code in a specific CPU.
15
16Performance is measured in terms of throughput as well as processor resource
17consumption. The tool currently works for processors with an out-of-order
18backend, for which there is a scheduling model available in LLVM.
19
20The main goal of this tool is not just to predict the performance of the code
21when run on the target, but also help with diagnosing potential performance
22issues.
23
24Given an assembly code sequence, llvm-mca estimates the IPC (Instructions Per
25Cycle), as well as hardware resource pressure. The analysis and reporting style
26were inspired by the IACA tool from Intel.
27
28OPTIONS
29-------
30
31If ``input`` is "``-``" or omitted, :program:`llvm-mca` reads from standard
32input. Otherwise, it will read from the specified filename.
33
34If the :option:`-o` option is omitted, then :program:`llvm-mca` will send its output
35to standard output if the input is from standard input.  If the :option:`-o`
36option specifies "``-``", then the output will also be sent to standard output.
37
38
39.. option:: -help
40
41 Print a summary of command line options.
42
43.. option:: -mtriple=<target triple>
44
45 Specify a target triple string.
46
47.. option:: -march=<arch>
48
49 Specify the architecture for which to analyze the code. It defaults to the
50 host default target.
51
52.. option:: -mcpu=<cpuname>
53
54 Specify the processor for whic to run the analysis.
55 By default this defaults to a "generic" processor. It is not autodetected to
56 the current architecture.
57
58.. option:: -output-asm-variant=<variant id>
59
60 Specify the output assembly variant for the report generated by the tool.
61 On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables
62 the AT&T (vic. Intel) assembly format for the code printed out by the tool in
63 the analysis report.
64
65.. option:: -dispatch=<width>
66
67 Specify a different dispatch width for the processor. The dispatch width
68 defaults to the 'IssueWidth' specified by the processor scheduling model.
69 If width is zero, then the default dispatch width is used.
70
71.. option:: -max-retire-per-cycle=<retire throughput>
72
73 Specify the retire throughput (i.e. how many instructions can be retired by the
74 retire control unit every cycle).
75
76.. option:: -register-file-size=<size>
77
78 Specify the size of the register file. When specified, this flag limits
79 how many temporary registers are available for register renaming purposes. By
80 default, the number of temporary registers is unlimited. A value of zero for
81 this flag means "unlimited number of temporary registers".
82
83.. option:: -iterations=<number of iterations>
84
85 Specify the number of iterations to run. If this flag is set to 0, then the
86 tool sets the number of iterations to a default value (i.e. 70).
87
88.. option:: -noalias=<bool>
89
90  If set, the tool assumes that loads and stores don't alias. This is the
91  default behavior.
92
93.. option:: -lqueue=<load queue size>
94
95  Specify the size of the load queue in the load/store unit emulated by the tool.
96  By default, the tool assumes an unbound number of entries in the load queue.
97  A value of zero for this flag is ignored, and the default load queue size is
98  used instead.
99
100.. option:: -squeue=<store queue size>
101
102  Specify the size of the store queue in the load/store unit emulated by the
103  tool. By default, the tool assumes an unbound number of entries in the store
104  queue. A value of zero for this flag is ignored, and the default store queue
105  size is used instead.
106
107.. option:: -verbose
108
109  Enable verbose output. In particular, this flag enables a number of extra
110  statistics and performance counters for the dispatch logic, the reorder
111  buffer, the retire control unit and the register file.
112
113.. option:: -timeline
114
115  Enable the timeline view.
116
117.. option:: -timeline-max-iterations=<iterations>
118
119  Limit the number of iterations to print in the timeline view. By default, the
120  timeline view prints information for up to 10 iterations.
121
122.. option:: -timeline-max-cycles=<cycles>
123
124  Limit the number of cycles in the timeline view. By default, the number of
125  cycles is set to 80.
126
127.. option:: -resource-pressure
128
129  Enable the resource pressure view. This is enabled by default.
130
131.. option:: -register-file-stats
132
133  Enable register file usage statistics.
134
135.. option:: -instruction-info
136
137  Enable the instruction info view. This is enabled by default.
138
139.. option:: -instruction-tables
140
141  Prints resource pressure information based on the static information
142  available from the processor model. This differs from the resource pressure
143  view because it doesn't require that the code is simulated. It instead prints
144  the theoretical uniform distribution of resource pressure for every
145  instruction in sequence.
146
147
148EXIT STATUS
149-----------
150
151:program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed
152to standard error, and the tool returns 1.
153
154