Lines Matching +full:clang +full:- +full:format +full:- +full:3
1 .. role:: raw-html(raw)
2 :format: html
5 LLVM Code Coverage Mapping Format
14 LLVM's code coverage mapping format is used to provide code coverage
15 analysis using LLVM's and Clang's instrumenation based profiling
16 (Clang's ``-fprofile-instr-generate`` option).
20 to know how it works under the hood. A prior knowledge of how Clang's profile
23 We start by showing how to use LLVM and Clang for code coverage analysis,
24 then we briefly desribe LLVM's code coverage mapping format and the
25 way that Clang and LLVM's code coverage tool work with this format. After
26 the basics are down, more advanced features of the coverage mapping format
27 are discussed - such as the data structures, LLVM IR representation and
36 * First, compile an instrumented version of your program using Clang's
37 ``-fprofile-instr-generate`` option with the additional ``-fcoverage-mapping``
40 ``clang -o test -fprofile-instr-generate -fcoverage-mapping test.c``
45 * After that, merge the profile data using the *llvm-profdata* tool:
47 ``llvm-profdata merge -o test.profdata default.profraw``
48 * Finally, run LLVM's code coverage tool (*llvm-cov*) to produce the code
51 ``llvm-cov show ./test -instr-profile=test.profdata test.c``
56 LLVM's code coverage mapping format is designed to be a self contained
57 data format, that can be embedded into the LLVM IR and object files.
58 It's described in this document as a **mapping** format because its goal is
65 1. When clang compiles a source file with ``-fcoverage-mapping``, it
71 2. It is also used by *llvm-cov* - the mapping information is extracted from an
77 The coverage mapping format aims to be a "universal format" that would be
78 suitable for usage by any frontend, and not just by Clang. It also aims to
80 data in order to reduce the size of the IR and object files - for example,
89 coverage mapping format works.
91 The coverage mapping format operates on a per-function level as the
98 --------------
113 …:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char…
114 <span style='background-color:#4A789C'> </span>
115 …-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ …
116 <span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span>
117 …<span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </sp…
118 <span style='background-color:#F6D55D'> printf("\n"); </span>
119 …<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> …
120 <span style='background-color:#4A789C'> return 0; </span>
121 <span style='background-color:#4A789C'>}</span>
124 by Clang's preprocessor. They don't associate with
127 inside a function as non-code lines that don't have execution counts.
130 …:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style…
131 …<span style='background-color:#85C1F5'>#ifdef DEBUG </span> <span class='c1'>// Skip…
132 <span style='background-color:#85C1F5'> printf("Hello world"); </span>
133 …<span style='background-color:#85C1F5'>#</span><span style='background-color:#4A789C'>endif …
134 <span style='background-color:#4A789C'> return 0; </span>
135 <span style='background-color:#4A789C'>}</span>
137 * Expansion regions are used to represent Clang's macro expansions. They
138 have an additional property - *expanded file id*. This property can be
147 …:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int func(int x) </span><span …
148 …-color:#4A789C'> #define MAX(x,y) </span><span style='background-color:#85C1F5'>((x) > (y)? </…
149 …-color:#4A789C'> return </span><span style='background-color:#7FCA9F'>MAX</span><span style='back…
150 <span style='background-color:#4A789C'>}</span>
168 It enables Clang to produce mapping information for the code
171 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>void func(const char *str) </s…
172 …e='background-color:#4A789C'> #define PUT </span><span style='background-color:#85C1F5'>printf("%…
173 <span style='background-color:#4A789C'> if(*str) </span>
174 <span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span>…
175 …-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-…
176 <span style='background-color:#4A789C'>}</span>
198 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char …
199 <span style='background-color:#4A789C'> </span>
200 <span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C…
201 <span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span><span> </s…
202 …-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='backgro…
203 <span style='background-color:#F6D55D'> printf("\n"); </span>
204 <span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> …
205 <span style='background-color:#4A789C'> return 0; </span>
206 <span style='background-color:#4A789C'>}</span>
213 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style=…
214 <span style='background-color:#4A789C'> return 0; </span>
215 …style='background-color:#4A789C'> </span><span style='background-color:#85C1F5'>printf("Hello wor…
216 <span style='background-color:#4A789C'>}</span>
235 .. code-block:: c
244 The coverage mapping variable generated by Clang has 3 fields:
252 .. code-block:: llvm
261 i32 1, ; Coverage mapping format version
279 .. code-block:: llvm
281 …{ i8*, i32, i32, i64 } { i8* getelementptr inbounds ([3 x i8]* @__profn_foo, i32 0, i32 0), ; Func…
282 i32 3, ; Function's name length
289 ------------------------
299 * The format version. The current version is 2 (encoded as a 1).
304 ----------------
308 .. code-block:: llvm
316 -------------
338 .. code-block:: llvm
342 * The string contains values that are encoded in the LEB128 format, which is
349 .. code-block:: llvm
367 .. code-block:: llvm
373 …+----------+--------------------------------------------------------------------------------------…
375 …+----------+--------------------------------------------------------------------------------------…
377 …+----------+--------------------------------------------------------------------------------------…
379 …+----------+--------------------------------------------------------------------------------------…
381 …+----------+--------------------------------------------------------------------------------------…
384 …+----------+--------------------------------------------------------------------------------------…
386 …+----------+--------------------------------------------------------------------------------------…
388 …+----------+--------------------------------------------------------------------------------------…
390 …+----------+--------------------------------------------------------------------------------------…
392 …+----------+--------------------------------------------------------------------------------------…
404 The per-function coverage mapping data is encoded as a stream of bytes,
406 `types <cvmtypes_>`_ like variable-length unsigned integers, that
410 The format of the structure follows:
415 `types <cvmtypes_>`_ as the per-function coverage mapping data, with the
423 -----
425 This section describes the basic types that are used by the encoding format
450 ---------------
458 -------
463 It is composed of two things --- the `tag <counter-tag_>`_
467 .. _counter-tag:
476 * 0 - The counter is zero.
478 * 1 - The counter is a reference to the profile instrumentation counter.
480 * 2 - The counter is a subtraction expression.
482 * 3 - The counter is an addition expression.
499 -------------------
505 The expression's kind is determined from the `tag <counter-tag_>`_ of the
511 ---------------
515 The mapping regions are stored in an array of sub-arrays where every
516 region in a particular sub-array has the same file id.
518 The file id for a sub-array of regions is the index of that
519 sub-array in the main array e.g. The first sub-array will have the file id
522 Sub-Array of Regions
535 The mapping region record contains two sub-records ---
549 ``[pseudo-counter]``
554 pseudo-counters --- if the tag is zero, than this header contains a
555 pseudo-counter, otherwise this header contains an ordinary counter.
560 A mapping region whose header has a counter with a non-zero tag is
563 Pseudo-Counter:
568 A pseudo-counter is stored in a single `LEB value <LEB128_>`_, just like
571 * bits 0-1: tag, which is always 0.
582 * 0 - This mapping region is a code region with a counter of zero.
583 * 2 - This mapping region is a skipped region.
598 sub-array, then it stores the starting line of that region.