1.. role:: raw-html(raw) 2 :format: html 3 4================================= 5LLVM Code Coverage Mapping Format 6================================= 7 8.. contents:: 9 :local: 10 11Introduction 12============ 13 14LLVM's code coverage mapping format is used to provide code coverage 15analysis using LLVM's and Clang's instrumentation based profiling 16(Clang's ``-fprofile-instr-generate`` option). 17 18This document is aimed at those who would like to know how LLVM's code coverage 19mapping works under the hood. A prior knowledge of how Clang's profile guided 20optimization works is useful, but not required. For those interested in using 21LLVM to provide code coverage analysis for their own programs, see the `Clang 22documentation <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`. 23 24We start by briefly describing LLVM's code coverage mapping format and the 25way that Clang and LLVM's code coverage tool work with this format. After 26the basics are down, more advanced features of the coverage mapping format 27are discussed - such as the data structures, LLVM IR representation and 28the binary encoding. 29 30High Level Overview 31=================== 32 33LLVM's code coverage mapping format is designed to be a self contained 34data format that can be embedded into the LLVM IR and into object files. 35It's described in this document as a **mapping** format because its goal is 36to store the data that is required for a code coverage tool to map between 37the specific source ranges in a file and the execution counts obtained 38after running the instrumented version of the program. 39 40The mapping data is used in two places in the code coverage process: 41 421. When clang compiles a source file with ``-fcoverage-mapping``, it 43 generates the mapping information that describes the mapping between the 44 source ranges and the profiling instrumentation counters. 45 This information gets embedded into the LLVM IR and conveniently 46 ends up in the final executable file when the program is linked. 47 482. It is also used by *llvm-cov* - the mapping information is extracted from an 49 object file and is used to associate the execution counts (the values of the 50 profile instrumentation counters), and the source ranges in a file. 51 After that, the tool is able to generate various code coverage reports 52 for the program. 53 54The coverage mapping format aims to be a "universal format" that would be 55suitable for usage by any frontend, and not just by Clang. It also aims to 56provide the frontend the possibility of generating the minimal coverage mapping 57data in order to reduce the size of the IR and object files - for example, 58instead of emitting mapping information for each statement in a function, the 59frontend is allowed to group the statements with the same execution count into 60regions of code, and emit the mapping information only for those regions. 61 62Advanced Concepts 63================= 64 65The remainder of this guide is meant to give you insight into the way the 66coverage mapping format works. 67 68The coverage mapping format operates on a per-function level as the 69profile instrumentation counters are associated with a specific function. 70For each function that requires code coverage, the frontend has to create 71coverage mapping data that can map between the source code ranges and 72the profile instrumentation counters for that function. 73 74Mapping Region 75-------------- 76 77The function's coverage mapping data contains an array of mapping regions. 78A mapping region stores the `source code range`_ that is covered by this region, 79the `file id <coverage file id_>`_, the `coverage mapping counter`_ and 80the region's kind. 81There are several kinds of mapping regions: 82 83* Code regions associate portions of source code and `coverage mapping 84 counters`_. They make up the majority of the mapping regions. They are used 85 by the code coverage tool to compute the execution counts for lines, 86 highlight the regions of code that were never executed, and to obtain 87 the various code coverage statistics for a function. 88 For example: 89 90 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:40 to 9:2</span> 91 <span style='background-color:#4A789C'> </span> 92 <span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ </span> <span class='c1'>// Code Region from 3:17 to 5:4</span> 93 <span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span> 94 <span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{ </span> <span class='c1'>// Code Region from 5:10 to 7:4</span> 95 <span style='background-color:#F6D55D'> printf("\n"); </span> 96 <span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span> 97 <span style='background-color:#4A789C'> return 0; </span> 98 <span style='background-color:#4A789C'>}</span> 99 </pre>` 100* Skipped regions are used to represent source ranges that were skipped 101 by Clang's preprocessor. They don't associate with 102 `coverage mapping counters`_, as the frontend knows that they are never 103 executed. They are used by the code coverage tool to mark the skipped lines 104 inside a function as non-code lines that don't have execution counts. 105 For example: 106 107 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:12 to 6:2</span> 108 <span style='background-color:#85C1F5'>#ifdef DEBUG </span> <span class='c1'>// Skipped Region from 2:1 to 4:2</span> 109 <span style='background-color:#85C1F5'> printf("Hello world"); </span> 110 <span style='background-color:#85C1F5'>#</span><span style='background-color:#4A789C'>endif </span> 111 <span style='background-color:#4A789C'> return 0; </span> 112 <span style='background-color:#4A789C'>}</span> 113 </pre>` 114* Expansion regions are used to represent Clang's macro expansions. They 115 have an additional property - *expanded file id*. This property can be 116 used by the code coverage tool to find the mapping regions that are created 117 as a result of this macro expansion, by checking if their file id matches the 118 expanded file id. They don't associate with `coverage mapping counters`_, 119 as the code coverage tool can determine the execution count for this region 120 by looking up the execution count of the first region with a corresponding 121 file id. 122 For example: 123 124 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int func(int x) </span><span style='background-color:#4A789C'>{ </span> 125 <span style='background-color:#4A789C'> #define MAX(x,y) </span><span style='background-color:#85C1F5'>((x) > (y)? </span><span style='background-color:#F6D55D'>(x)</span><span style='background-color:#85C1F5'> : </span><span style='background-color:#F4BA70'>(y)</span><span style='background-color:#85C1F5'>)</span><span style='background-color:#4A789C'> </span> 126 <span style='background-color:#4A789C'> return </span><span style='background-color:#7FCA9F'>MAX</span><span style='background-color:#4A789C'>(x, 42); </span> <span class='c1'>// Expansion Region from 3:10 to 3:13</span> 127 <span style='background-color:#4A789C'>}</span> 128 </pre>` 129* Branch regions associate instrumentable branch conditions in the source code 130 with a `coverage mapping counter`_ to track how many times an individual 131 condition evaluated to 'true' and another `coverage mapping counter`_ to 132 track how many times that condition evaluated to false. Instrumentable 133 branch conditions may comprise larger boolean expressions using boolean 134 logical operators. The 'true' and 'false' cases reflect unique branch paths 135 that can be traced back to the source code. 136 For example: 137 138 :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int func(int x, int y) { 139 <span> if (<span style='background-color:#4A789C'>(x > 1)</span> || <span style='background-color:#4A789C'>(y > 3)</span>) {</span> <span class='c1'>// Branch Region from 3:6 to 3:12</span> 140 <span> </span><span class='c1'>// Branch Region from 3:17 to 3:23</span> 141 <span> printf("%d\n", x); </span> 142 <span> } else { </span> 143 <span> printf("\n"); </span> 144 <span> }</span> 145 <span> return 0; </span> 146 <span>}</span> 147 </pre>` 148 149* Decision regions associate multiple branch regions with a boolean 150 expression in the source code. This information also includes the number of 151 bitmap bits needed to represent the expression's executed test vectors as 152 well as the total number of instrumentable branch conditions that comprise 153 the expression. Decision regions are used to visualize Modified 154 Condition/Decision Coverage (MC/DC) in *llvm-cov* for each boolean 155 expression. When decision regions are used, control flow IDs are assigned to 156 each associated branch region. One ID represents the current branch 157 condition, and two additional IDs represent the next branch condition in the 158 control flow given a true or false evaluation, respectively. This allows 159 *llvm-cov* to reconstruct the control flow around the conditions in order to 160 comprehend the full list of potential executable test vectors. 161 162.. _source code range: 163 164Source Range: 165^^^^^^^^^^^^^ 166 167The source range record contains the starting and ending location of a certain 168mapping region. Both locations include the line and the column numbers. 169 170.. _coverage file id: 171 172File ID: 173^^^^^^^^ 174 175The file id an integer value that tells us 176in which source file or macro expansion is this region located. 177It enables Clang to produce mapping information for the code 178defined inside macros, like this example demonstrates: 179 180:raw-html:`<pre class='highlight' style='line-height:initial;'><span>void func(const char *str) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:28 to 6:2 with file id 0</span> 181<span style='background-color:#4A789C'> #define PUT </span><span style='background-color:#85C1F5'>printf("%s\n", str)</span><span style='background-color:#4A789C'> </span> <span class='c1'>// 2 Code Regions from 2:15 to 2:34 with file ids 1 and 2</span> 182<span style='background-color:#4A789C'> if(*str) </span> 183<span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Expansion Region from 4:5 to 4:8 with file id 0 that expands a macro with file id 1</span> 184<span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Expansion Region from 5:3 to 5:6 with file id 0 that expands a macro with file id 2</span> 185<span style='background-color:#4A789C'>}</span> 186</pre>` 187 188.. _coverage mapping counter: 189.. _coverage mapping counters: 190 191Counter: 192^^^^^^^^ 193 194A coverage mapping counter can represent a reference to the profile 195instrumentation counter. The execution count for a region with such counter 196is determined by looking up the value of the corresponding profile 197instrumentation counter. 198 199It can also represent a binary arithmetical expression that operates on 200coverage mapping counters or other expressions. 201The execution count for a region with an expression counter is determined by 202evaluating the expression's arguments and then adding them together or 203subtracting them from one another. 204In the example below, a subtraction expression is used to compute the execution 205count for the compound statement that follows the *else* keyword: 206 207:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Region's counter is a reference to the profile counter #0</span> 208<span style='background-color:#4A789C'> </span> 209<span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ </span> <span class='c1'>// Region's counter is a reference to the profile counter #1</span> 210<span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span><span> </span> 211<span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{ </span> <span class='c1'>// Region's counter is an expression (reference to the profile counter #0 - reference to the profile counter #1)</span> 212<span style='background-color:#F6D55D'> printf("\n"); </span> 213<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span> 214<span style='background-color:#4A789C'> return 0; </span> 215<span style='background-color:#4A789C'>}</span> 216</pre>` 217 218Finally, a coverage mapping counter can also represent an execution count of 219of zero. The zero counter is used to provide coverage mapping for 220unreachable statements and expressions, like in the example below: 221 222:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span> 223<span style='background-color:#4A789C'> return 0; </span> 224<span style='background-color:#4A789C'> </span><span style='background-color:#85C1F5'>printf("Hello world!\n")</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Unreachable region's counter is zero</span> 225<span style='background-color:#4A789C'>}</span> 226</pre>` 227 228The zero counters allow the code coverage tool to display proper line execution 229counts for the unreachable lines and highlight the unreachable code. 230Without them, the tool would think that those lines and regions were still 231executed, as it doesn't possess the frontend's knowledge. 232 233Note that branch regions are created to track branch conditions in the source 234code and refer to two coverage mapping counters, one to track the number of 235times the branch condition evaluated to "true", and one to track the number of 236times the branch condition evaluated to "false". 237 238LLVM IR Representation 239====================== 240 241The coverage mapping data is stored in the LLVM IR using a global constant 242structure variable called *__llvm_coverage_mapping* with the *IPSK_covmap* 243section specifier (i.e. ".lcovmap$M" on Windows and "__llvm_covmap" elsewhere). 244 245For example, let’s consider a C file and how it gets compiled to LLVM: 246 247.. _coverage mapping sample: 248 249.. code-block:: c 250 251 int foo() { 252 return 42; 253 } 254 int bar() { 255 return 13; 256 } 257 258The coverage mapping variable generated by Clang has 2 fields: 259 260* Coverage mapping header. 261 262* An optionally compressed list of filenames present in the translation unit. 263 264The variable has 8-byte alignment because ld64 cannot always pack symbols from 265different object files tightly (the word-level alignment assumption is baked in 266too deeply). 267 268.. code-block:: llvm 269 270 @__llvm_coverage_mapping = internal constant { { i32, i32, i32, i32 }, [32 x i8] } 271 { 272 { i32, i32, i32, i32 } ; Coverage map header 273 { 274 i32 0, ; Always 0. In prior versions, the number of affixed function records 275 i32 32, ; The length of the string that contains the encoded translation unit filenames 276 i32 0, ; Always 0. In prior versions, the length of the affixed string that contains the encoded coverage mapping data 277 i32 3, ; Coverage mapping format version 278 }, 279 [32 x i8] c"..." ; Encoded data (dissected later) 280 }, section "__llvm_covmap", align 8 281 282The current version of the format is version 6. 283 284There is one difference between versions 6 and 5: 285 286* The first entry in the filename list is the compilation directory. When the 287 filename is relative, the compilation directory is combined with the relative 288 path to get an absolute path. This can reduce size by omitting the duplicate 289 prefix in filenames. 290 291There is one difference between versions 5 and 4: 292 293* The notion of branch region has been introduced along with a corresponding 294 region kind. Branch regions encode two counters, one to track how many 295 times a "true" branch condition is taken, and one to track how many times a 296 "false" branch condition is taken. 297 298There are two differences between versions 4 and 3: 299 300* Function records are now named symbols, and are marked *linkonce_odr*. This 301 allows linkers to merge duplicate function records. Merging of duplicate 302 *dummy* records (emitted for functions included-but-not-used in a translation 303 unit) reduces size bloat in the coverage mapping data. As part of this 304 change, region mapping information for a function is now included within the 305 function record, instead of being affixed to the coverage header. 306 307* The filename list for a translation unit may optionally be zlib-compressed. 308 309The only difference between versions 3 and 2 is that a special encoding for 310column end locations was introduced to indicate gap regions. 311 312In version 1, the function record for *foo* was defined as follows: 313 314.. code-block:: llvm 315 316 { i8*, i32, i32, i64 } { i8* getelementptr inbounds ([3 x i8]* @__profn_foo, i32 0, i32 0), ; Function's name 317 i32 3, ; Function's name length 318 i32 9, ; Function's encoded coverage mapping data string length 319 i64 0 ; Function's structural hash 320 } 321 322In version 2, the function record for *foo* was defined as follows: 323 324.. code-block:: llvm 325 326 { i64, i32, i64 } { 327 i64 0x5cf8c24cdb18bdac, ; Function's name MD5 328 i32 9, ; Function's encoded coverage mapping data string length 329 i64 0 ; Function's structural hash 330 331Coverage Mapping Header: 332------------------------ 333 334As shown above, the coverage mapping header has the following fields: 335 336* The number of function records affixed to the coverage header. Always 0, but present for backwards compatibility. 337 338* The length of the string in the third field of *__llvm_coverage_mapping* that contains the encoded translation unit filenames. 339 340* The length of the string in the third field of *__llvm_coverage_mapping* that contains any encoded coverage mapping data affixed to the coverage header. Always 0, but present for backwards compatibility. 341 342* The format version. The current version is 6 (encoded as a 5). 343 344.. _function records: 345 346Function record: 347---------------- 348 349A function record is a structure of the following type: 350 351.. code-block:: llvm 352 353 { i64, i32, i64, i64, [? x i8] } 354 355It contains the function name's MD5, the length of the encoded mapping data for 356that function, the function's structural hash value, the hash of the filenames 357in the function's translation unit, and the encoded mapping data. 358 359Dissecting the sample: 360^^^^^^^^^^^^^^^^^^^^^^ 361 362Here's an overview of the encoded data that was stored in the 363IR for the `coverage mapping sample`_ that was shown earlier: 364 365* The IR contains the following string constant that represents the encoded 366 coverage mapping data for the sample translation unit: 367 368 .. code-block:: llvm 369 370 c"\01\15\1Dx\DA\13\D1\0F-N-*\D6/+\CE\D6/\C9-\D0O\CB\CF\D7K\06\00N+\07]" 371 372* The string contains values that are encoded in the LEB128 format, which is 373 used throughout for storing integers. It also contains a compressed payload. 374 375* The first three LEB128-encoded numbers in the sample specify the number of 376 filenames, the length of the uncompressed filenames, and the length of the 377 compressed payload (or 0 if compression is disabled). In this sample, there 378 is 1 filename that is 21 bytes in length (uncompressed), and stored in 29 379 bytes (compressed). 380 381* The coverage mapping from the first function record is encoded in this string: 382 383 .. code-block:: llvm 384 385 c"\01\00\00\01\01\01\0C\02\02" 386 387 This string consists of the following bytes: 388 389 +----------+-------------------------------------------------------------------------------------------------------------------------+ 390 | ``0x01`` | The number of file ids used by this function. There is only one file id used by the mapping data in this function. | 391 +----------+-------------------------------------------------------------------------------------------------------------------------+ 392 | ``0x00`` | An index into the filenames array which corresponds to the file "/Users/alex/test.c". | 393 +----------+-------------------------------------------------------------------------------------------------------------------------+ 394 | ``0x00`` | The number of counter expressions used by this function. This function doesn't use any expressions. | 395 +----------+-------------------------------------------------------------------------------------------------------------------------+ 396 | ``0x01`` | The number of mapping regions that are stored in an array for the function's file id #0. | 397 +----------+-------------------------------------------------------------------------------------------------------------------------+ 398 | ``0x01`` | The coverage mapping counter for the first region in this function. The value of 1 tells us that it's a coverage | 399 | | mapping counter that is a reference to the profile instrumentation counter with an index of 0. | 400 +----------+-------------------------------------------------------------------------------------------------------------------------+ 401 | ``0x01`` | The starting line of the first mapping region in this function. | 402 +----------+-------------------------------------------------------------------------------------------------------------------------+ 403 | ``0x0C`` | The starting column of the first mapping region in this function. | 404 +----------+-------------------------------------------------------------------------------------------------------------------------+ 405 | ``0x02`` | The ending line of the first mapping region in this function. | 406 +----------+-------------------------------------------------------------------------------------------------------------------------+ 407 | ``0x02`` | The ending column of the first mapping region in this function. | 408 +----------+-------------------------------------------------------------------------------------------------------------------------+ 409 410* The length of the substring that contains the encoded coverage mapping data 411 for the second function record is also 9. It's structured like the mapping data 412 for the first function record. 413 414* The two trailing bytes are zeroes and are used to pad the coverage mapping 415 data to give it the 8 byte alignment. 416 417Encoding 418======== 419 420The per-function coverage mapping data is encoded as a stream of bytes, 421with a simple structure. The structure consists of the encoding 422`types <cvmtypes_>`_ like variable-length unsigned integers, that 423are used to encode `File ID Mapping`_, `Counter Expressions`_ and 424the `Mapping Regions`_. 425 426The format of the structure follows: 427 428 ``[file id mapping, counter expressions, mapping regions]`` 429 430The translation unit filenames are encoded using the same encoding 431`types <cvmtypes_>`_ as the per-function coverage mapping data, with the 432following structure: 433 434 ``[numFilenames : LEB128, filename0 : string, filename1 : string, ...]`` 435 436.. _cvmtypes: 437 438Types 439----- 440 441This section describes the basic types that are used by the encoding format 442and can appear after ``:`` in the ``[foo : type]`` description. 443 444.. _LEB128: 445 446LEB128 447^^^^^^ 448 449LEB128 is an unsigned integer value that is encoded using DWARF's LEB128 450encoding, optimizing for the case where values are small 451(1 byte for values less than 128). 452 453.. _CoverageStrings: 454 455Strings 456^^^^^^^ 457 458``[length : LEB128, characters...]`` 459 460String values are encoded with a `LEB value <LEB128_>`_ for the length 461of the string and a sequence of bytes for its characters. 462 463.. _file id mapping: 464 465File ID Mapping 466--------------- 467 468``[numIndices : LEB128, filenameIndex0 : LEB128, filenameIndex1 : LEB128, ...]`` 469 470File id mapping in a function's coverage mapping stream 471contains the indices into the translation unit's filenames array. 472 473Counter 474------- 475 476``[value : LEB128]`` 477 478A `coverage mapping counter`_ is stored in a single `LEB value <LEB128_>`_. 479It is composed of two things --- the `tag <counter-tag_>`_ 480which is stored in the lowest 2 bits, and the `counter data`_ which is stored 481in the remaining bits. 482 483.. _counter-tag: 484 485Tag: 486^^^^ 487 488The counter's tag encodes the counter's kind 489and, if the counter is an expression, the expression's kind. 490The possible tag values are: 491 492* 0 - The counter is zero. 493 494* 1 - The counter is a reference to the profile instrumentation counter. 495 496* 2 - The counter is a subtraction expression. 497 498* 3 - The counter is an addition expression. 499 500.. _counter data: 501 502Data: 503^^^^^ 504 505The counter's data is interpreted in the following manner: 506 507* When the counter is a reference to the profile instrumentation counter, 508 then the counter's data is the id of the profile counter. 509* When the counter is an expression, then the counter's data 510 is the index into the array of counter expressions. 511 512.. _Counter Expressions: 513 514Counter Expressions 515------------------- 516 517``[numExpressions : LEB128, expr0LHS : LEB128, expr0RHS : LEB128, expr1LHS : LEB128, expr1RHS : LEB128, ...]`` 518 519Counter expressions consist of two counters as they 520represent binary arithmetic operations. 521The expression's kind is determined from the `tag <counter-tag_>`_ of the 522counter that references this expression. 523 524.. _Mapping Regions: 525 526Mapping Regions 527--------------- 528 529``[numRegionArrays : LEB128, regionsForFile0, regionsForFile1, ...]`` 530 531The mapping regions are stored in an array of sub-arrays where every 532region in a particular sub-array has the same file id. 533 534The file id for a sub-array of regions is the index of that 535sub-array in the main array e.g. The first sub-array will have the file id 536of 0. 537 538Sub-Array of Regions 539^^^^^^^^^^^^^^^^^^^^ 540 541``[numRegions : LEB128, region0, region1, ...]`` 542 543The mapping regions for a specific file id are stored in an array that is 544sorted in an ascending order by the region's starting location. 545 546Mapping Region 547^^^^^^^^^^^^^^ 548 549``[header, source range]`` 550 551The mapping region record contains two sub-records --- 552the `header`_, which stores the counter and/or the region's kind, 553and the `source range`_ that contains the starting and ending 554location of this region. 555 556.. _header: 557 558Header 559^^^^^^ 560 561``[counter]`` 562 563or 564 565``[pseudo-counter]`` 566 567The header encodes the region's counter and the region's kind. A branch region 568will encode two counters. 569 570The value of the counter's tag distinguishes between the counters and 571pseudo-counters --- if the tag is zero, than this header contains a 572pseudo-counter, otherwise this header contains an ordinary counter. 573 574Counter: 575"""""""" 576 577A mapping region whose header has a counter with a non-zero tag is 578a code region. 579 580Pseudo-Counter: 581""""""""""""""" 582 583``[value : LEB128]`` 584 585A pseudo-counter is stored in a single `LEB value <LEB128_>`_, just like 586the ordinary counter. It has the following interpretation: 587 588* bits 0-1: tag, which is always 0. 589 590* bit 2: expansionRegionTag. If this bit is set, then this mapping region 591 is an expansion region. 592 593* remaining bits: data. If this region is an expansion region, then the data 594 contains the expanded file id of that region. 595 596 Otherwise, the data contains the region's kind. The possible region 597 kind values are: 598 599 * 0 - This mapping region is a code region with a counter of zero. 600 * 2 - This mapping region is a skipped region. 601 * 4 - This mapping region is a branch region. 602 603.. _source range: 604 605Source Range 606^^^^^^^^^^^^ 607 608``[deltaLineStart : LEB128, columnStart : LEB128, numLines : LEB128, columnEnd : LEB128]`` 609 610The source range record contains the following fields: 611 612* *deltaLineStart*: The difference between the starting line of the 613 current mapping region and the starting line of the previous mapping region. 614 615 If the current mapping region is the first region in the current 616 sub-array, then it stores the starting line of that region. 617 618* *columnStart*: The starting column of the mapping region. 619 620* *numLines*: The difference between the ending line and the starting line 621 of the current mapping region. 622 623* *columnEnd*: The ending column of the mapping region. If the high bit is set, 624 the current mapping region is a gap area. A count for a gap area is only used 625 as the line execution count if there are no other regions on a line. 626 627Testing Format 628============== 629 630.. warning:: 631 This section is for the LLVM developers who are working on ``llvm-cov`` only. 632 633``llvm-cov`` uses a special file format (called ``.covmapping`` below) for 634testing purposes. This format is private and should have no use for general 635users. As a developer, you can get such files by the ``convert-for-testing`` 636subcommand of ``llvm-cov``. 637 638The structure of the ``.covmapping`` files follows: 639 640``[magicNumber : u64, version : u64, profileNames, coverageMapping, coverageRecords]`` 641 642Magic Number and Version 643------------------------ 644 645The magic is ``0x6d766f636d766c6c``, which is the ASCII string 646``llvmcovm`` in little-endian. 647 648There are two versions for now: 649 650- Version1, encoded as ``0x6174616474736574`` (ASCII string ``testdata``). 651- Version2, encoded as 1. 652 653The only difference between Version1 and Version2 is in the encoding of the 654``coverageMapping`` fields, which is explained later. 655 656Profile Names 657------------- 658 659``profileNames``, ``coverageMapping`` and ``coverageRecords`` are 3 sections 660extracted from the original binary file. 661 662``profileNames`` encodes the size, address and the raw data of the section: 663 664``[profileNamesSize : LEB128, profileNamesAddr : LEB128, profileNamesData : bytes]`` 665 666Coverage Mapping 667---------------- 668 669This field is padded with zero bytes to make it 8-byte aligned. 670 671``coverageMapping`` contains the records of the source files. In version 1, 672only one record is stored: 673 674``[padding : bytes, coverageMappingData : bytes]`` 675 676Version 2 relaxes this restriction by encoding the size of 677``coverageMappingData`` as a LEB128 number before the data: 678 679``[coverageMappingSize : LEB128, padding : bytes, coverageMappingData : bytes]`` 680 681The current version is 2. 682 683Coverage Records 684---------------- 685 686This field is padded with zero bytes to make it 8-byte aligned. 687 688``coverageRecords`` is encoded as: 689 690``[padding : bytes, coverageRecordsData : bytes]`` 691 692The rest data in the file is considered as the ``coverageRecordsData``. 693