llvm.org GIT mirror llvm / 498e1aa
[docs][Remarks] Add documentation for remarks in LLVM This adds documentation that describes remarks in LLVM. It aims at explaining what remarks are, how to enable them, and what users can do with the different modes. It lists all the available flags in LLVM (excluding clang), and describes the expected YAML structure as well as the tools that support the YAML format today. Differential Revision: https://reviews.llvm.org/D64355 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@365578 91177308-0d34-0410-b5e6-96231b3b80d8 Francis Visoiu Mistrih a month ago
3 changed file(s) with 308 addition(s) and 14 deletion(s). Raw diff Collapse all Expand all
16131613 allocated in the function prologue. Functions with dynamic stack allocations are
16141614 not included.
16151615
1616 Emitting remark diagnostics in the object file
1617 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1618
1619 A section containing metadata on remark diagnostics will be emitted when
1620 -remarks-section is passed. The section contains:
1621
1622 * a magic number: "REMARKS\\0"
1623 * the version number: a little-endian uint64_t
1624 * the total size of the string table (the size itself excluded):
1625 little-endian uint64_t
1626 * a list of null-terminated strings
1627 * the absolute file path to the serialized remark diagnostics: a
1628 null-terminated string.
1629
16301616 VLIW Packetizer
16311617 ---------------
16321618
0 =======
1 Remarks
2 =======
3
4 .. contents::
5 :local:
6
7 Introduction to the LLVM remark diagnostics
8 ===========================================
9
10 LLVM is able to emit diagnostics from passes describing whether an optimization
11 has been performed or missed for a particular reason, which should give more
12 insight to users about what the compiler did during the compilation pipeline.
13
14 There are three main remark types:
15
16 ``Passed``
17
18 Remarks that describe a successful optimization performed by the compiler.
19
20 :Example:
21
22 ::
23
24 foo inlined into bar with (cost=always): always inline attribute
25
26 ``Missed``
27
28 Remarks that describe an attempt to an optimization by the compiler that
29 could not be performed.
30
31 :Example:
32
33 ::
34
35 foo not inlined into bar because it should never be inlined
36 (cost=never): noinline function attribute
37
38 ``Analysis``
39
40 Remarks that describe the result of an analysis, that can bring more
41 information to the user regarding the generated code.
42
43 :Example:
44
45 ::
46
47 16 stack bytes in function
48
49 ::
50
51 10 instructions in function
52
53 Enabling optimization remarks
54 =============================
55
56 There are two modes that are supported for enabling optimization remarks in
57 LLVM: through remark diagnostics, or through serialized remarks.
58
59 Remark diagnostics
60 ------------------
61
62 Optimization remarks can be emitted as diagnostics. These diagnostics will be
63 propagated to front-ends if desired, or emitted by tools like :doc:`llc
64 ` or :doc:`opt `.
65
66 .. option:: -pass-remarks=
67
68 Enables optimization remarks from passes whose name match the given (POSIX)
69 regular expression.
70
71 .. option:: -pass-remarks-missed=
72
73 Enables missed optimization remarks from passes whose name match the given
74 (POSIX) regular expression.
75
76 .. option:: -pass-remarks-analysis=
77
78 Enables optimization analysis remarks from passes whose name match the given
79 (POSIX) regular expression.
80
81 Serialized remarks
82 ------------------
83
84 While diagnostics are useful during development, it is often more useful to
85 refer to optimization remarks post-compilation, typically during performance
86 analysis.
87
88 For that, LLVM can serialize the remarks produced for each compilation unit to
89 a file that can be consumed later.
90
91 By default, the format of the serialized remarks is :ref:`YAML
92 `, and it can be accompanied by a :ref:`section `
93 in the object files to easily retrieve it.
94
95 :doc:`llc ` and :doc:`opt ` support the
96 following options:
97
98
99 ``Basic options``
100
101 .. option:: -pass-remarks-output=
102
103 Enables the serialization of remarks to a file specified in .
104
105 By default, the output is serialized to :ref:`YAML `.
106
107 .. option:: -pass-remarks-format=
108
109 Specifies the output format of the serialized remarks.
110
111 Supported formats:
112
113 * :ref:`yaml ` (default)
114
115 ``Content configuration``
116
117 .. option:: -pass-remarks-filter=
118
119 Only passes whose name match the given (POSIX) regular expression will be
120 serialized to the final output.
121
122 .. option:: -pass-remarks-with-hotness
123
124 With PGO, include profile count in optimization remarks.
125
126 .. option:: -pass-remarks-hotness-threshold
127
128 The minimum profile count required for an optimization remark to be
129 emitted.
130
131 Other tools that support remarks:
132
133 :program:`llvm-lto`
134
135 .. option:: -lto-pass-remarks-output=
136 .. option:: -lto-pass-remarks-filter=
137 .. option:: -lto-pass-remarks-format=
138 .. option:: -lto-pass-remarks-with-hotness
139 .. option:: -lto-pass-remarks-hotness-threshold
140
141 :program:`gold-plugin` and :program:`lld`
142
143 .. option:: -opt-remarks-filename=
144 .. option:: -opt-remarks-filter=
145 .. option:: -opt-remarks-format=
146 .. option:: -opt-remarks-with-hotness
147
148 .. _yamlremarks:
149
150 YAML remarks
151 ============
152
153 A typical remark serialized to YAML looks like this:
154
155 .. code-block:: yaml
156
157 --- !
158 Pass:
159 Name:
160 DebugLoc: { File: , Line: , Column: }
161 Function:
162 Hotness:
163 Args:
164 - :
165 DebugLoc: { File: , Line: , Column: }
166
167 The following entries are mandatory:
168
169 * ````: can be ``Passed``, ``Missed``, ``Analysis``,
170 ``AnalysisFPCommute``, ``AnalysisAliasing``, ``Failure``.
171 * ````: the name of the pass that emitted this remark.
172 * ````: the name of the remark coming from ````.
173 * ````: the mangled name of the function.
174
175 If a ``DebugLoc`` entry is specified, the following fields are required:
176
177 * ````
178 * ````
179 * ````
180
181 If an ``arg`` entry is specified, the following fields are required:
182
183 * ````
184 * ````
185
186 If a ``DebugLoc`` entry is specified within an ``arg`` entry, the following
187 fields are required:
188
189 * ````
190 * ````
191 * ````
192
193 opt-viewer
194 ==========
195
196 The ``opt-viewer`` directory contains a collection of tools that visualize and
197 summarize serialized remarks.
198
199 .. _optviewerpy:
200
201 opt-viewer.py
202 -------------
203
204 Output a HTML page which gives visual feedback on compiler interactions with
205 your program.
206
207 :Examples:
208
209 ::
210
211 $ opt-viewer.py my_yaml_file.opt.yaml
212
213 ::
214
215 $ opt-viewer.py my_build_dir/
216
217
218 opt-stats.py
219 ------------
220
221 Output statistics about the optimization remarks in the input set.
222
223 :Example:
224
225 ::
226
227 $ opt-stats.py my_yaml_file.opt.yaml
228
229 Total number of remarks 3
230
231
232 Top 10 remarks by pass:
233 inline 33%
234 asm-printer 33%
235 prologepilog 33%
236
237 Top 10 remarks:
238 asm-printer/InstructionCount 33%
239 inline/NoDefinition 33%
240 prologepilog/StackSize 33%
241
242 opt-diff.py
243 -----------
244
245 Produce a new YAML file which contains all of the changes in optimizations
246 between two YAML files.
247
248 Typically, this tool should be used to do diffs between:
249
250 * new compiler + fixed source vs old compiler + fixed source
251 * fixed compiler + new source vs fixed compiler + old source
252
253 This diff file can be displayed using :ref:`opt-viewer.py `.
254
255 :Example:
256
257 ::
258
259 $ opt-diff.py my_opt_yaml1.opt.yaml my_opt_yaml2.opt.yaml -o my_opt_diff.opt.yaml
260 $ opt-viewer.py my_opt_diff.opt.yaml
261
262 .. _remarkssection:
263
264 Emitting remark diagnostics in the object file
265 ==============================================
266
267 A section containing metadata on remark diagnostics will be emitted when
268 -remarks-section is passed. The section contains:
269
270 * a magic number: "REMARKS\\0"
271 * the version number: a little-endian uint64_t
272 * the total size of the string table (the size itself excluded):
273 little-endian uint64_t
274 * a list of null-terminated strings
275 * the absolute file path to the serialized remark diagnostics: a
276 null-terminated string.
277
278 The section is named:
279
280 * ``__LLVM,__remarks`` (MachO)
281 * ``.remarks`` (ELF)
282
283 C API
284 =====
285
286 LLVM provides a library that can be used to parse remarks through a shared
287 library named ``libRemarks``.
288
289 The typical usage through the C API is like the following:
290
291 .. code-block:: c
292
293 LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
294 LLVMRemarkEntryRef Remark = NULL;
295 while ((Remark = LLVMRemarkParserGetNext(Parser))) {
296 // use Remark
297 }
298 bool HasError = LLVMRemarkParserHasError(Parser);
299 LLVMRemarkParserDispose(Parser);
300
301 .. FIXME: add documentation for llvm-opt-report.
302 .. FIXME: add documentation for Passes supporting optimization remarks
303 .. FIXME: add documentation for IR Passes
304 .. FIXME: add documentation for CodeGen Passes
9595 Benchmarking
9696 Docker
9797 BuildingADistribution
98 Remarks
9899
99100 :doc:`GettingStarted`
100101 Discusses how to get up and running quickly with the LLVM infrastructure.
181182 A best-practices guide for using LLVM's CMake build system to package and
182183 distribute LLVM-based tools.
183184
185 :doc:`Remarks`
186 A reference on the implementation of remarks in LLVM.
184187
185188 Programming Documentation
186189 =========================