1*0a6a1f1dSLionel Sambuc.. role:: raw-html(raw) 2*0a6a1f1dSLionel Sambuc :format: html 3*0a6a1f1dSLionel Sambuc 4*0a6a1f1dSLionel Sambuc================================= 5*0a6a1f1dSLionel SambucLLVM Code Coverage Mapping Format 6*0a6a1f1dSLionel Sambuc================================= 7*0a6a1f1dSLionel Sambuc 8*0a6a1f1dSLionel Sambuc.. contents:: 9*0a6a1f1dSLionel Sambuc :local: 10*0a6a1f1dSLionel Sambuc 11*0a6a1f1dSLionel SambucIntroduction 12*0a6a1f1dSLionel Sambuc============ 13*0a6a1f1dSLionel Sambuc 14*0a6a1f1dSLionel SambucLLVM's code coverage mapping format is used to provide code coverage 15*0a6a1f1dSLionel Sambucanalysis using LLVM's and Clang's instrumenation based profiling 16*0a6a1f1dSLionel Sambuc(Clang's ``-fprofile-instr-generate`` option). 17*0a6a1f1dSLionel Sambuc 18*0a6a1f1dSLionel SambucThis document is aimed at those who use LLVM's code coverage mapping to provide 19*0a6a1f1dSLionel Sambuccode coverage analysis for their own programs, and for those who would like 20*0a6a1f1dSLionel Sambucto know how it works under the hood. A prior knowledge of how Clang's profile 21*0a6a1f1dSLionel Sambucguided optimization works is useful, but not required. 22*0a6a1f1dSLionel Sambuc 23*0a6a1f1dSLionel SambucWe start by showing how to use LLVM and Clang for code coverage analysis, 24*0a6a1f1dSLionel Sambucthen we briefly desribe LLVM's code coverage mapping format and the 25*0a6a1f1dSLionel Sambucway that Clang and LLVM's code coverage tool work with this format. After 26*0a6a1f1dSLionel Sambucthe basics are down, more advanced features of the coverage mapping format 27*0a6a1f1dSLionel Sambucare discussed - such as the data structures, LLVM IR representation and 28*0a6a1f1dSLionel Sambucthe binary encoding. 29*0a6a1f1dSLionel Sambuc 30*0a6a1f1dSLionel SambucQuick Start 31*0a6a1f1dSLionel Sambuc=========== 32*0a6a1f1dSLionel Sambuc 33*0a6a1f1dSLionel SambucHere's a short story that describes how to generate code coverage overview 34*0a6a1f1dSLionel Sambucfor a sample source file called *test.c*. 35*0a6a1f1dSLionel Sambuc 36*0a6a1f1dSLionel Sambuc* First, compile an instrumented version of your program using Clang's 37*0a6a1f1dSLionel Sambuc ``-fprofile-instr-generate`` option with the additional ``-fcoverage-mapping`` 38*0a6a1f1dSLionel Sambuc option: 39*0a6a1f1dSLionel Sambuc 40*0a6a1f1dSLionel Sambuc ``clang -o test -fprofile-instr-generate -fcoverage-mapping test.c`` 41*0a6a1f1dSLionel Sambuc* Then, run the instrumented binary. The runtime will produce a file called 42*0a6a1f1dSLionel Sambuc *default.profraw* containing the raw profile instrumentation data: 43*0a6a1f1dSLionel Sambuc 44*0a6a1f1dSLionel Sambuc ``./test`` 45*0a6a1f1dSLionel Sambuc* After that, merge the profile data using the *llvm-profdata* tool: 46*0a6a1f1dSLionel Sambuc 47*0a6a1f1dSLionel Sambuc ``llvm-profdata merge -o test.profdata default.profraw`` 48*0a6a1f1dSLionel Sambuc* Finally, run LLVM's code coverage tool (*llvm-cov*) to produce the code 49*0a6a1f1dSLionel Sambuc coverage overview for the sample source file: 50*0a6a1f1dSLionel Sambuc 51*0a6a1f1dSLionel Sambuc ``llvm-cov show ./test -instr-profile=test.profdata test.c`` 52*0a6a1f1dSLionel Sambuc 53*0a6a1f1dSLionel SambucHigh Level Overview 54*0a6a1f1dSLionel Sambuc=================== 55*0a6a1f1dSLionel Sambuc 56*0a6a1f1dSLionel SambucLLVM's code coverage mapping format is designed to be a self contained 57*0a6a1f1dSLionel Sambucdata format, that can be embedded into the LLVM IR and object files. 58*0a6a1f1dSLionel SambucIt's described in this document as a **mapping** format because its goal is 59*0a6a1f1dSLionel Sambucto store the data that is required for a code coverage tool to map between 60*0a6a1f1dSLionel Sambucthe specific source ranges in a file and the execution counts obtained 61*0a6a1f1dSLionel Sambucafter running the instrumented version of the program. 62*0a6a1f1dSLionel Sambuc 63*0a6a1f1dSLionel SambucThe mapping data is used in two places in the code coverage process: 64*0a6a1f1dSLionel Sambuc 65*0a6a1f1dSLionel Sambuc1. When clang compiles a source file with ``-fcoverage-mapping``, it 66*0a6a1f1dSLionel Sambuc generates the mapping information that describes the mapping between the 67*0a6a1f1dSLionel Sambuc source ranges and the profiling instrumentation counters. 68*0a6a1f1dSLionel Sambuc This information gets embedded into the LLVM IR and conveniently 69*0a6a1f1dSLionel Sambuc ends up in the final executable file when the program is linked. 70*0a6a1f1dSLionel Sambuc 71*0a6a1f1dSLionel Sambuc2. It is also used by *llvm-cov* - the mapping information is extracted from an 72*0a6a1f1dSLionel Sambuc object file and is used to associate the execution counts (the values of the 73*0a6a1f1dSLionel Sambuc profile instrumentation counters), and the source ranges in a file. 74*0a6a1f1dSLionel Sambuc After that, the tool is able to generate various code coverage reports 75*0a6a1f1dSLionel Sambuc for the program. 76*0a6a1f1dSLionel Sambuc 77*0a6a1f1dSLionel SambucThe coverage mapping format aims to be a "universal format" that would be 78*0a6a1f1dSLionel Sambucsuitable for usage by any frontend, and not just by Clang. It also aims to 79*0a6a1f1dSLionel Sambucprovide the frontend the possibility of generating the minimal coverage mapping 80*0a6a1f1dSLionel Sambucdata in order to reduce the size of the IR and object files - for example, 81*0a6a1f1dSLionel Sambucinstead of emitting mapping information for each statement in a function, the 82*0a6a1f1dSLionel Sambucfrontend is allowed to group the statements with the same execution count into 83*0a6a1f1dSLionel Sambucregions of code, and emit the mapping information only for those regions. 84*0a6a1f1dSLionel Sambuc 85*0a6a1f1dSLionel SambucAdvanced Concepts 86*0a6a1f1dSLionel Sambuc================= 87*0a6a1f1dSLionel Sambuc 88*0a6a1f1dSLionel SambucThe remainder of this guide is meant to give you insight into the way the 89*0a6a1f1dSLionel Sambuccoverage mapping format works. 90*0a6a1f1dSLionel Sambuc 91*0a6a1f1dSLionel SambucThe coverage mapping format operates on a per-function level as the 92*0a6a1f1dSLionel Sambucprofile instrumentation counters are associated with a specific function. 93*0a6a1f1dSLionel SambucFor each function that requires code coverage, the frontend has to create 94*0a6a1f1dSLionel Sambuccoverage mapping data that can map between the source code ranges and 95*0a6a1f1dSLionel Sambucthe profile instrumentation counters for that function. 96*0a6a1f1dSLionel Sambuc 97*0a6a1f1dSLionel SambucMapping Region 98*0a6a1f1dSLionel Sambuc-------------- 99*0a6a1f1dSLionel Sambuc 100*0a6a1f1dSLionel SambucThe function's coverage mapping data contains an array of mapping regions. 101*0a6a1f1dSLionel SambucA mapping region stores the `source code range`_ that is covered by this region, 102*0a6a1f1dSLionel Sambucthe `file id <coverage file id_>`_, the `coverage mapping counter`_ and 103*0a6a1f1dSLionel Sambucthe region's kind. 104*0a6a1f1dSLionel SambucThere are several kinds of mapping regions: 105*0a6a1f1dSLionel Sambuc 106*0a6a1f1dSLionel Sambuc* Code regions associate portions of source code and `coverage mapping 107*0a6a1f1dSLionel Sambuc counters`_. They make up the majority of the mapping regions. They are used 108*0a6a1f1dSLionel Sambuc by the code coverage tool to compute the execution counts for lines, 109*0a6a1f1dSLionel Sambuc highlight the regions of code that were never executed, and to obtain 110*0a6a1f1dSLionel Sambuc the various code coverage statistics for a function. 111*0a6a1f1dSLionel Sambuc For example: 112*0a6a1f1dSLionel Sambuc 113*0a6a1f1dSLionel Sambuc :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> 114*0a6a1f1dSLionel Sambuc <span style='background-color:#4A789C'> </span> 115*0a6a1f1dSLionel Sambuc <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> 116*0a6a1f1dSLionel Sambuc <span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span> 117*0a6a1f1dSLionel Sambuc <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> 118*0a6a1f1dSLionel Sambuc <span style='background-color:#F6D55D'> printf("\n"); </span> 119*0a6a1f1dSLionel Sambuc <span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span> 120*0a6a1f1dSLionel Sambuc <span style='background-color:#4A789C'> return 0; </span> 121*0a6a1f1dSLionel Sambuc <span style='background-color:#4A789C'>}</span> 122*0a6a1f1dSLionel Sambuc </pre>` 123*0a6a1f1dSLionel Sambuc* Skipped regions are used to represent source ranges that were skipped 124*0a6a1f1dSLionel Sambuc by Clang's preprocessor. They don't associate with 125*0a6a1f1dSLionel Sambuc `coverage mapping counters`_, as the frontend knows that they are never 126*0a6a1f1dSLionel Sambuc executed. They are used by the code coverage tool to mark the skipped lines 127*0a6a1f1dSLionel Sambuc inside a function as non-code lines that don't have execution counts. 128*0a6a1f1dSLionel Sambuc For example: 129*0a6a1f1dSLionel Sambuc 130*0a6a1f1dSLionel Sambuc :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> 131*0a6a1f1dSLionel Sambuc <span style='background-color:#85C1F5'>#ifdef DEBUG </span> <span class='c1'>// Skipped Region from 2:1 to 4:2</span> 132*0a6a1f1dSLionel Sambuc <span style='background-color:#85C1F5'> printf("Hello world"); </span> 133*0a6a1f1dSLionel Sambuc <span style='background-color:#85C1F5'>#</span><span style='background-color:#4A789C'>endif </span> 134*0a6a1f1dSLionel Sambuc <span style='background-color:#4A789C'> return 0; </span> 135*0a6a1f1dSLionel Sambuc <span style='background-color:#4A789C'>}</span> 136*0a6a1f1dSLionel Sambuc </pre>` 137*0a6a1f1dSLionel Sambuc* Expansion regions are used to represent Clang's macro expansions. They 138*0a6a1f1dSLionel Sambuc have an additional property - *expanded file id*. This property can be 139*0a6a1f1dSLionel Sambuc used by the code coverage tool to find the mapping regions that are created 140*0a6a1f1dSLionel Sambuc as a result of this macro expansion, by checking if their file id matches the 141*0a6a1f1dSLionel Sambuc expanded file id. They don't associate with `coverage mapping counters`_, 142*0a6a1f1dSLionel Sambuc as the code coverage tool can determine the execution count for this region 143*0a6a1f1dSLionel Sambuc by looking up the execution count of the first region with a corresponding 144*0a6a1f1dSLionel Sambuc file id. 145*0a6a1f1dSLionel Sambuc For example: 146*0a6a1f1dSLionel Sambuc 147*0a6a1f1dSLionel Sambuc :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int func(int x) </span><span style='background-color:#4A789C'>{ </span> 148*0a6a1f1dSLionel Sambuc <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> 149*0a6a1f1dSLionel Sambuc <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> 150*0a6a1f1dSLionel Sambuc <span style='background-color:#4A789C'>}</span> 151*0a6a1f1dSLionel Sambuc </pre>` 152*0a6a1f1dSLionel Sambuc 153*0a6a1f1dSLionel Sambuc.. _source code range: 154*0a6a1f1dSLionel Sambuc 155*0a6a1f1dSLionel SambucSource Range: 156*0a6a1f1dSLionel Sambuc^^^^^^^^^^^^^ 157*0a6a1f1dSLionel Sambuc 158*0a6a1f1dSLionel SambucThe source range record contains the starting and ending location of a certain 159*0a6a1f1dSLionel Sambucmapping region. Both locations include the line and the column numbers. 160*0a6a1f1dSLionel Sambuc 161*0a6a1f1dSLionel Sambuc.. _coverage file id: 162*0a6a1f1dSLionel Sambuc 163*0a6a1f1dSLionel SambucFile ID: 164*0a6a1f1dSLionel Sambuc^^^^^^^^ 165*0a6a1f1dSLionel Sambuc 166*0a6a1f1dSLionel SambucThe file id an integer value that tells us 167*0a6a1f1dSLionel Sambucin which source file or macro expansion is this region located. 168*0a6a1f1dSLionel SambucIt enables Clang to produce mapping information for the code 169*0a6a1f1dSLionel Sambucdefined inside macros, like this example demonstrates: 170*0a6a1f1dSLionel Sambuc 171*0a6a1f1dSLionel Sambuc: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> 172*0a6a1f1dSLionel Sambuc<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> 173*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'> if(*str) </span> 174*0a6a1f1dSLionel Sambuc<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> 175*0a6a1f1dSLionel Sambuc<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> 176*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'>}</span> 177*0a6a1f1dSLionel Sambuc</pre>` 178*0a6a1f1dSLionel Sambuc 179*0a6a1f1dSLionel Sambuc.. _coverage mapping counter: 180*0a6a1f1dSLionel Sambuc.. _coverage mapping counters: 181*0a6a1f1dSLionel Sambuc 182*0a6a1f1dSLionel SambucCounter: 183*0a6a1f1dSLionel Sambuc^^^^^^^^ 184*0a6a1f1dSLionel Sambuc 185*0a6a1f1dSLionel SambucA coverage mapping counter can represents a reference to the profile 186*0a6a1f1dSLionel Sambucinstrumentation counter. The execution count for a region with such counter 187*0a6a1f1dSLionel Sambucis determined by looking up the value of the corresponding profile 188*0a6a1f1dSLionel Sambucinstrumentation counter. 189*0a6a1f1dSLionel Sambuc 190*0a6a1f1dSLionel SambucIt can also represent a binary arithmetical expression that operates on 191*0a6a1f1dSLionel Sambuccoverage mapping counters or other expressions. 192*0a6a1f1dSLionel SambucThe execution count for a region with an expression counter is determined by 193*0a6a1f1dSLionel Sambucevaluating the expression's arguments and then adding them together or 194*0a6a1f1dSLionel Sambucsubtracting them from one another. 195*0a6a1f1dSLionel SambucIn the example below, a subtraction expression is used to compute the execution 196*0a6a1f1dSLionel Sambuccount for the compound statement that follows the *else* keyword: 197*0a6a1f1dSLionel Sambuc 198*0a6a1f1dSLionel Sambuc: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> 199*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'> </span> 200*0a6a1f1dSLionel Sambuc<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> 201*0a6a1f1dSLionel Sambuc<span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span><span> </span> 202*0a6a1f1dSLionel Sambuc<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> 203*0a6a1f1dSLionel Sambuc<span style='background-color:#F6D55D'> printf("\n"); </span> 204*0a6a1f1dSLionel Sambuc<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span> 205*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'> return 0; </span> 206*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'>}</span> 207*0a6a1f1dSLionel Sambuc</pre>` 208*0a6a1f1dSLionel Sambuc 209*0a6a1f1dSLionel SambucFinally, a coverage mapping counter can also represent an execution count of 210*0a6a1f1dSLionel Sambucof zero. The zero counter is used to provide coverage mapping for 211*0a6a1f1dSLionel Sambucunreachable statements and expressions, like in the example below: 212*0a6a1f1dSLionel Sambuc 213*0a6a1f1dSLionel Sambuc:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span> 214*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'> return 0; </span> 215*0a6a1f1dSLionel Sambuc<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> 216*0a6a1f1dSLionel Sambuc<span style='background-color:#4A789C'>}</span> 217*0a6a1f1dSLionel Sambuc</pre>` 218*0a6a1f1dSLionel Sambuc 219*0a6a1f1dSLionel SambucThe zero counters allow the code coverage tool to display proper line execution 220*0a6a1f1dSLionel Sambuccounts for the unreachable lines and highlight the unreachable code. 221*0a6a1f1dSLionel SambucWithout them, the tool would think that those lines and regions were still 222*0a6a1f1dSLionel Sambucexecuted, as it doesn't possess the frontend's knowledge. 223*0a6a1f1dSLionel Sambuc 224*0a6a1f1dSLionel SambucLLVM IR Representation 225*0a6a1f1dSLionel Sambuc====================== 226*0a6a1f1dSLionel Sambuc 227*0a6a1f1dSLionel SambucThe coverage mapping data is stored in the LLVM IR using a single global 228*0a6a1f1dSLionel Sambucconstant structure variable called *__llvm_coverage_mapping* 229*0a6a1f1dSLionel Sambucwith the *__llvm_covmap* section specifier. 230*0a6a1f1dSLionel Sambuc 231*0a6a1f1dSLionel SambucFor example, let’s consider a C file and how it gets compiled to LLVM: 232*0a6a1f1dSLionel Sambuc 233*0a6a1f1dSLionel Sambuc.. _coverage mapping sample: 234*0a6a1f1dSLionel Sambuc 235*0a6a1f1dSLionel Sambuc.. code-block:: c 236*0a6a1f1dSLionel Sambuc 237*0a6a1f1dSLionel Sambuc int foo() { 238*0a6a1f1dSLionel Sambuc return 42; 239*0a6a1f1dSLionel Sambuc } 240*0a6a1f1dSLionel Sambuc int bar() { 241*0a6a1f1dSLionel Sambuc return 13; 242*0a6a1f1dSLionel Sambuc } 243*0a6a1f1dSLionel Sambuc 244*0a6a1f1dSLionel SambucThe coverage mapping variable generated by Clang is: 245*0a6a1f1dSLionel Sambuc 246*0a6a1f1dSLionel Sambuc.. code-block:: llvm 247*0a6a1f1dSLionel Sambuc 248*0a6a1f1dSLionel Sambuc @__llvm_coverage_mapping = internal constant { i32, i32, i32, i32, [2 x { i8*, i32, i32 }], [40 x i8] } 249*0a6a1f1dSLionel Sambuc { i32 2, ; The number of function records 250*0a6a1f1dSLionel Sambuc i32 20, ; The length of the string that contains the encoded translation unit filenames 251*0a6a1f1dSLionel Sambuc i32 20, ; The length of the string that contains the encoded coverage mapping data 252*0a6a1f1dSLionel Sambuc i32 0, ; Coverage mapping format version 253*0a6a1f1dSLionel Sambuc [2 x { i8*, i32, i32 }] [ ; Function records 254*0a6a1f1dSLionel Sambuc { i8*, i32, i32 } { i8* getelementptr inbounds ([3 x i8]* @__llvm_profile_name_foo, i32 0, i32 0), ; Function's name 255*0a6a1f1dSLionel Sambuc i32 3, ; Function's name length 256*0a6a1f1dSLionel Sambuc i32 9 ; Function's encoded coverage mapping data string length 257*0a6a1f1dSLionel Sambuc }, 258*0a6a1f1dSLionel Sambuc { i8*, i32, i32 } { i8* getelementptr inbounds ([3 x i8]* @__llvm_profile_name_bar, i32 0, i32 0), ; Function's name 259*0a6a1f1dSLionel Sambuc i32 3, ; Function's name length 260*0a6a1f1dSLionel Sambuc i32 9 ; Function's encoded coverage mapping data string length 261*0a6a1f1dSLionel Sambuc }], 262*0a6a1f1dSLionel Sambuc [40 x i8] c"..." ; Encoded data (dissected later) 263*0a6a1f1dSLionel Sambuc }, section "__llvm_covmap", align 8 264*0a6a1f1dSLionel Sambuc 265*0a6a1f1dSLionel SambucVersion: 266*0a6a1f1dSLionel Sambuc-------- 267*0a6a1f1dSLionel Sambuc 268*0a6a1f1dSLionel SambucThe coverage mapping version number can have the following values: 269*0a6a1f1dSLionel Sambuc 270*0a6a1f1dSLionel Sambuc* 0 — The first (current) version of the coverage mapping format. 271*0a6a1f1dSLionel Sambuc 272*0a6a1f1dSLionel Sambuc.. _function records: 273*0a6a1f1dSLionel Sambuc 274*0a6a1f1dSLionel SambucFunction record: 275*0a6a1f1dSLionel Sambuc---------------- 276*0a6a1f1dSLionel Sambuc 277*0a6a1f1dSLionel SambucA function record is a structure of the following type: 278*0a6a1f1dSLionel Sambuc 279*0a6a1f1dSLionel Sambuc.. code-block:: llvm 280*0a6a1f1dSLionel Sambuc 281*0a6a1f1dSLionel Sambuc { i8*, i32, i32 } 282*0a6a1f1dSLionel Sambuc 283*0a6a1f1dSLionel SambucIt contains the pointer to the function's name, function's name length, 284*0a6a1f1dSLionel Sambucand the length of the encoded mapping data for that function. 285*0a6a1f1dSLionel Sambuc 286*0a6a1f1dSLionel SambucEncoded data: 287*0a6a1f1dSLionel Sambuc------------- 288*0a6a1f1dSLionel Sambuc 289*0a6a1f1dSLionel SambucThe encoded data is stored in a single string that contains 290*0a6a1f1dSLionel Sambucthe encoded filenames used by this translation unit and the encoded coverage 291*0a6a1f1dSLionel Sambucmapping data for each function in this translation unit. 292*0a6a1f1dSLionel Sambuc 293*0a6a1f1dSLionel SambucThe encoded data has the following structure: 294*0a6a1f1dSLionel Sambuc 295*0a6a1f1dSLionel Sambuc``[filenames, coverageMappingDataForFunctionRecord0, coverageMappingDataForFunctionRecord1, ..., padding]`` 296*0a6a1f1dSLionel Sambuc 297*0a6a1f1dSLionel SambucIf necessary, the encoded data is padded with zeroes so that the size 298*0a6a1f1dSLionel Sambucof the data string is rounded up to the nearest multiple of 8 bytes. 299*0a6a1f1dSLionel Sambuc 300*0a6a1f1dSLionel SambucDissecting the sample: 301*0a6a1f1dSLionel Sambuc^^^^^^^^^^^^^^^^^^^^^^ 302*0a6a1f1dSLionel Sambuc 303*0a6a1f1dSLionel SambucHere's an overview of the encoded data that was stored in the 304*0a6a1f1dSLionel SambucIR for the `coverage mapping sample`_ that was shown earlier: 305*0a6a1f1dSLionel Sambuc 306*0a6a1f1dSLionel Sambuc* The IR contains the following string constant that represents the encoded 307*0a6a1f1dSLionel Sambuc coverage mapping data for the sample translation unit: 308*0a6a1f1dSLionel Sambuc 309*0a6a1f1dSLionel Sambuc .. code-block:: llvm 310*0a6a1f1dSLionel Sambuc 311*0a6a1f1dSLionel Sambuc c"\01\12/Users/alex/test.c\01\00\00\01\01\01\0C\02\02\01\00\00\01\01\04\0C\02\02\00\00" 312*0a6a1f1dSLionel Sambuc 313*0a6a1f1dSLionel Sambuc* The string contains values that are encoded in the LEB128 format, which is 314*0a6a1f1dSLionel Sambuc used throughout for storing integers. It also contains a string value. 315*0a6a1f1dSLionel Sambuc 316*0a6a1f1dSLionel Sambuc* The length of the substring that contains the encoded translation unit 317*0a6a1f1dSLionel Sambuc filenames is the value of the second field in the *__llvm_coverage_mapping* 318*0a6a1f1dSLionel Sambuc structure, which is 20, thus the filenames are encoded in this string: 319*0a6a1f1dSLionel Sambuc 320*0a6a1f1dSLionel Sambuc .. code-block:: llvm 321*0a6a1f1dSLionel Sambuc 322*0a6a1f1dSLionel Sambuc c"\01\12/Users/alex/test.c" 323*0a6a1f1dSLionel Sambuc 324*0a6a1f1dSLionel Sambuc This string contains the following data: 325*0a6a1f1dSLionel Sambuc 326*0a6a1f1dSLionel Sambuc * Its first byte has a value of ``0x01``. It stores the number of filenames 327*0a6a1f1dSLionel Sambuc contained in this string. 328*0a6a1f1dSLionel Sambuc * Its second byte stores the length of the first filename in this string. 329*0a6a1f1dSLionel Sambuc * The remaining 18 bytes are used to store the first filename. 330*0a6a1f1dSLionel Sambuc 331*0a6a1f1dSLionel Sambuc* The length of the substring that contains the encoded coverage mapping data 332*0a6a1f1dSLionel Sambuc for the first function is the value of the third field in the first 333*0a6a1f1dSLionel Sambuc structure in an array of `function records`_ stored in the 334*0a6a1f1dSLionel Sambuc fifth field of the *__llvm_coverage_mapping* structure, which is the 9. 335*0a6a1f1dSLionel Sambuc Therefore, the coverage mapping for the first function record is encoded 336*0a6a1f1dSLionel Sambuc in this string: 337*0a6a1f1dSLionel Sambuc 338*0a6a1f1dSLionel Sambuc .. code-block:: llvm 339*0a6a1f1dSLionel Sambuc 340*0a6a1f1dSLionel Sambuc c"\01\00\00\01\01\01\0C\02\02" 341*0a6a1f1dSLionel Sambuc 342*0a6a1f1dSLionel Sambuc This string consists of the following bytes: 343*0a6a1f1dSLionel Sambuc 344*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 345*0a6a1f1dSLionel Sambuc | ``0x01`` | The number of file ids used by this function. There is only one file id used by the mapping data in this function. | 346*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 347*0a6a1f1dSLionel Sambuc | ``0x00`` | An index into the filenames array which corresponds to the file "/Users/alex/test.c". | 348*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 349*0a6a1f1dSLionel Sambuc | ``0x00`` | The number of counter expressions used by this function. This function doesn't use any expressions. | 350*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 351*0a6a1f1dSLionel Sambuc | ``0x01`` | The number of mapping regions that are stored in an array for the function's file id #0. | 352*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 353*0a6a1f1dSLionel Sambuc | ``0x01`` | The coverage mapping counter for the first region in this function. The value of 1 tells us that it's a coverage | 354*0a6a1f1dSLionel Sambuc | | mapping counter that is a reference ot the profile instrumentation counter with an index of 0. | 355*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 356*0a6a1f1dSLionel Sambuc | ``0x01`` | The starting line of the first mapping region in this function. | 357*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 358*0a6a1f1dSLionel Sambuc | ``0x0C`` | The starting column of the first mapping region in this function. | 359*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 360*0a6a1f1dSLionel Sambuc | ``0x02`` | The ending line of the first mapping region in this function. | 361*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 362*0a6a1f1dSLionel Sambuc | ``0x02`` | The ending column of the first mapping region in this function. | 363*0a6a1f1dSLionel Sambuc +----------+-------------------------------------------------------------------------------------------------------------------------+ 364*0a6a1f1dSLionel Sambuc 365*0a6a1f1dSLionel Sambuc* The length of the substring that contains the encoded coverage mapping data 366*0a6a1f1dSLionel Sambuc for the second function record is also 9. It's structured like the mapping data 367*0a6a1f1dSLionel Sambuc for the first function record. 368*0a6a1f1dSLionel Sambuc 369*0a6a1f1dSLionel Sambuc* The two trailing bytes are zeroes and are used to pad the coverage mapping 370*0a6a1f1dSLionel Sambuc data to give it the 8 byte alignment. 371*0a6a1f1dSLionel Sambuc 372*0a6a1f1dSLionel SambucEncoding 373*0a6a1f1dSLionel Sambuc======== 374*0a6a1f1dSLionel Sambuc 375*0a6a1f1dSLionel SambucThe per-function coverage mapping data is encoded as a stream of bytes, 376*0a6a1f1dSLionel Sambucwith a simple structure. The structure consists of the encoding 377*0a6a1f1dSLionel Sambuc`types <cvmtypes_>`_ like variable-length unsigned integers, that 378*0a6a1f1dSLionel Sambucare used to encode `File ID Mapping`_, `Counter Expressions`_ and 379*0a6a1f1dSLionel Sambucthe `Mapping Regions`_. 380*0a6a1f1dSLionel Sambuc 381*0a6a1f1dSLionel SambucThe format of the structure follows: 382*0a6a1f1dSLionel Sambuc 383*0a6a1f1dSLionel Sambuc ``[file id mapping, counter expressions, mapping regions]`` 384*0a6a1f1dSLionel Sambuc 385*0a6a1f1dSLionel SambucThe translation unit filenames are encoded using the same encoding 386*0a6a1f1dSLionel Sambuc`types <cvmtypes_>`_ as the per-function coverage mapping data, with the 387*0a6a1f1dSLionel Sambucfollowing structure: 388*0a6a1f1dSLionel Sambuc 389*0a6a1f1dSLionel Sambuc ``[numFilenames : LEB128, filename0 : string, filename1 : string, ...]`` 390*0a6a1f1dSLionel Sambuc 391*0a6a1f1dSLionel Sambuc.. _cvmtypes: 392*0a6a1f1dSLionel Sambuc 393*0a6a1f1dSLionel SambucTypes 394*0a6a1f1dSLionel Sambuc----- 395*0a6a1f1dSLionel Sambuc 396*0a6a1f1dSLionel SambucThis section describes the basic types that are used by the encoding format 397*0a6a1f1dSLionel Sambucand can appear after ``:`` in the ``[foo : type]`` description. 398*0a6a1f1dSLionel Sambuc 399*0a6a1f1dSLionel Sambuc.. _LEB128: 400*0a6a1f1dSLionel Sambuc 401*0a6a1f1dSLionel SambucLEB128 402*0a6a1f1dSLionel Sambuc^^^^^^ 403*0a6a1f1dSLionel Sambuc 404*0a6a1f1dSLionel SambucLEB128 is an unsigned interger value that is encoded using DWARF's LEB128 405*0a6a1f1dSLionel Sambucencoding, optimizing for the case where values are small 406*0a6a1f1dSLionel Sambuc(1 byte for values less than 128). 407*0a6a1f1dSLionel Sambuc 408*0a6a1f1dSLionel Sambuc.. _strings: 409*0a6a1f1dSLionel Sambuc 410*0a6a1f1dSLionel SambucStrings 411*0a6a1f1dSLionel Sambuc^^^^^^^ 412*0a6a1f1dSLionel Sambuc 413*0a6a1f1dSLionel Sambuc``[length : LEB128, characters...]`` 414*0a6a1f1dSLionel Sambuc 415*0a6a1f1dSLionel SambucString values are encoded with a `LEB value <LEB128_>`_ for the length 416*0a6a1f1dSLionel Sambucof the string and a sequence of bytes for its characters. 417*0a6a1f1dSLionel Sambuc 418*0a6a1f1dSLionel Sambuc.. _file id mapping: 419*0a6a1f1dSLionel Sambuc 420*0a6a1f1dSLionel SambucFile ID Mapping 421*0a6a1f1dSLionel Sambuc--------------- 422*0a6a1f1dSLionel Sambuc 423*0a6a1f1dSLionel Sambuc``[numIndices : LEB128, filenameIndex0 : LEB128, filenameIndex1 : LEB128, ...]`` 424*0a6a1f1dSLionel Sambuc 425*0a6a1f1dSLionel SambucFile id mapping in a function's coverage mapping stream 426*0a6a1f1dSLionel Sambuccontains the indices into the translation unit's filenames array. 427*0a6a1f1dSLionel Sambuc 428*0a6a1f1dSLionel SambucCounter 429*0a6a1f1dSLionel Sambuc------- 430*0a6a1f1dSLionel Sambuc 431*0a6a1f1dSLionel Sambuc``[value : LEB128]`` 432*0a6a1f1dSLionel Sambuc 433*0a6a1f1dSLionel SambucA `coverage mapping counter`_ is stored in a single `LEB value <LEB128_>`_. 434*0a6a1f1dSLionel SambucIt is composed of two things --- the `tag <counter-tag_>`_ 435*0a6a1f1dSLionel Sambucwhich is stored in the lowest 2 bits, and the `counter data`_ which is stored 436*0a6a1f1dSLionel Sambucin the remaining bits. 437*0a6a1f1dSLionel Sambuc 438*0a6a1f1dSLionel Sambuc.. _counter-tag: 439*0a6a1f1dSLionel Sambuc 440*0a6a1f1dSLionel SambucTag: 441*0a6a1f1dSLionel Sambuc^^^^ 442*0a6a1f1dSLionel Sambuc 443*0a6a1f1dSLionel SambucThe counter's tag encodes the counter's kind 444*0a6a1f1dSLionel Sambucand, if the counter is an expression, the expression's kind. 445*0a6a1f1dSLionel SambucThe possible tag values are: 446*0a6a1f1dSLionel Sambuc 447*0a6a1f1dSLionel Sambuc* 0 - The counter is zero. 448*0a6a1f1dSLionel Sambuc 449*0a6a1f1dSLionel Sambuc* 1 - The counter is a reference to the profile instrumentation counter. 450*0a6a1f1dSLionel Sambuc 451*0a6a1f1dSLionel Sambuc* 2 - The counter is a subtraction expression. 452*0a6a1f1dSLionel Sambuc 453*0a6a1f1dSLionel Sambuc* 3 - The counter is an addition expression. 454*0a6a1f1dSLionel Sambuc 455*0a6a1f1dSLionel Sambuc.. _counter data: 456*0a6a1f1dSLionel Sambuc 457*0a6a1f1dSLionel SambucData: 458*0a6a1f1dSLionel Sambuc^^^^^ 459*0a6a1f1dSLionel Sambuc 460*0a6a1f1dSLionel SambucThe counter's data is interpreted in the following manner: 461*0a6a1f1dSLionel Sambuc 462*0a6a1f1dSLionel Sambuc* When the counter is a reference to the profile instrumentation counter, 463*0a6a1f1dSLionel Sambuc then the counter's data is the id of the profile counter. 464*0a6a1f1dSLionel Sambuc* When the counter is an expression, then the counter's data 465*0a6a1f1dSLionel Sambuc is the index into the array of counter expressions. 466*0a6a1f1dSLionel Sambuc 467*0a6a1f1dSLionel Sambuc.. _Counter Expressions: 468*0a6a1f1dSLionel Sambuc 469*0a6a1f1dSLionel SambucCounter Expressions 470*0a6a1f1dSLionel Sambuc------------------- 471*0a6a1f1dSLionel Sambuc 472*0a6a1f1dSLionel Sambuc``[numExpressions : LEB128, expr0LHS : LEB128, expr0RHS : LEB128, expr1LHS : LEB128, expr1RHS : LEB128, ...]`` 473*0a6a1f1dSLionel Sambuc 474*0a6a1f1dSLionel SambucCounter expressions consist of two counters as they 475*0a6a1f1dSLionel Sambucrepresent binary arithmetic operations. 476*0a6a1f1dSLionel SambucThe expression's kind is determined from the `tag <counter-tag_>`_ of the 477*0a6a1f1dSLionel Sambuccounter that references this expression. 478*0a6a1f1dSLionel Sambuc 479*0a6a1f1dSLionel Sambuc.. _Mapping Regions: 480*0a6a1f1dSLionel Sambuc 481*0a6a1f1dSLionel SambucMapping Regions 482*0a6a1f1dSLionel Sambuc--------------- 483*0a6a1f1dSLionel Sambuc 484*0a6a1f1dSLionel Sambuc``[numRegionArrays : LEB128, regionsForFile0, regionsForFile1, ...]`` 485*0a6a1f1dSLionel Sambuc 486*0a6a1f1dSLionel SambucThe mapping regions are stored in an array of sub-arrays where every 487*0a6a1f1dSLionel Sambucregion in a particular sub-array has the same file id. 488*0a6a1f1dSLionel Sambuc 489*0a6a1f1dSLionel SambucThe file id for a sub-array of regions is the index of that 490*0a6a1f1dSLionel Sambucsub-array in the main array e.g. The first sub-array will have the file id 491*0a6a1f1dSLionel Sambucof 0. 492*0a6a1f1dSLionel Sambuc 493*0a6a1f1dSLionel SambucSub-Array of Regions 494*0a6a1f1dSLionel Sambuc^^^^^^^^^^^^^^^^^^^^ 495*0a6a1f1dSLionel Sambuc 496*0a6a1f1dSLionel Sambuc``[numRegions : LEB128, region0, region1, ...]`` 497*0a6a1f1dSLionel Sambuc 498*0a6a1f1dSLionel SambucThe mapping regions for a specific file id are stored in an array that is 499*0a6a1f1dSLionel Sambucsorted in an ascending order by the region's starting location. 500*0a6a1f1dSLionel Sambuc 501*0a6a1f1dSLionel SambucMapping Region 502*0a6a1f1dSLionel Sambuc^^^^^^^^^^^^^^ 503*0a6a1f1dSLionel Sambuc 504*0a6a1f1dSLionel Sambuc``[header, source range]`` 505*0a6a1f1dSLionel Sambuc 506*0a6a1f1dSLionel SambucThe mapping region record contains two sub-records --- 507*0a6a1f1dSLionel Sambucthe `header`_, which stores the counter and/or the region's kind, 508*0a6a1f1dSLionel Sambucand the `source range`_ that contains the starting and ending 509*0a6a1f1dSLionel Sambuclocation of this region. 510*0a6a1f1dSLionel Sambuc 511*0a6a1f1dSLionel Sambuc.. _header: 512*0a6a1f1dSLionel Sambuc 513*0a6a1f1dSLionel SambucHeader 514*0a6a1f1dSLionel Sambuc^^^^^^ 515*0a6a1f1dSLionel Sambuc 516*0a6a1f1dSLionel Sambuc``[counter]`` 517*0a6a1f1dSLionel Sambuc 518*0a6a1f1dSLionel Sambucor 519*0a6a1f1dSLionel Sambuc 520*0a6a1f1dSLionel Sambuc``[pseudo-counter]`` 521*0a6a1f1dSLionel Sambuc 522*0a6a1f1dSLionel SambucThe header encodes the region's counter and the region's kind. 523*0a6a1f1dSLionel Sambuc 524*0a6a1f1dSLionel SambucThe value of the counter's tag distinguishes between the counters and 525*0a6a1f1dSLionel Sambucpseudo-counters --- if the tag is zero, than this header contains a 526*0a6a1f1dSLionel Sambucpseudo-counter, otherwise this header contains an ordinary counter. 527*0a6a1f1dSLionel Sambuc 528*0a6a1f1dSLionel SambucCounter: 529*0a6a1f1dSLionel Sambuc"""""""" 530*0a6a1f1dSLionel Sambuc 531*0a6a1f1dSLionel SambucA mapping region whose header has a counter with a non-zero tag is 532*0a6a1f1dSLionel Sambuca code region. 533*0a6a1f1dSLionel Sambuc 534*0a6a1f1dSLionel SambucPseudo-Counter: 535*0a6a1f1dSLionel Sambuc""""""""""""""" 536*0a6a1f1dSLionel Sambuc 537*0a6a1f1dSLionel Sambuc``[value : LEB128]`` 538*0a6a1f1dSLionel Sambuc 539*0a6a1f1dSLionel SambucA pseudo-counter is stored in a single `LEB value <LEB128_>`_, just like 540*0a6a1f1dSLionel Sambucthe ordinary counter. It has the following interpretation: 541*0a6a1f1dSLionel Sambuc 542*0a6a1f1dSLionel Sambuc* bits 0-1: tag, which is always 0. 543*0a6a1f1dSLionel Sambuc 544*0a6a1f1dSLionel Sambuc* bit 2: expansionRegionTag. If this bit is set, then this mapping region 545*0a6a1f1dSLionel Sambuc is an expansion region. 546*0a6a1f1dSLionel Sambuc 547*0a6a1f1dSLionel Sambuc* remaining bits: data. If this region is an expansion region, then the data 548*0a6a1f1dSLionel Sambuc contains the expanded file id of that region. 549*0a6a1f1dSLionel Sambuc 550*0a6a1f1dSLionel Sambuc Otherwise, the data contains the region's kind. The possible region 551*0a6a1f1dSLionel Sambuc kind values are: 552*0a6a1f1dSLionel Sambuc 553*0a6a1f1dSLionel Sambuc * 0 - This mapping region is a code region with a counter of zero. 554*0a6a1f1dSLionel Sambuc * 2 - This mapping region is a skipped region. 555*0a6a1f1dSLionel Sambuc 556*0a6a1f1dSLionel Sambuc.. _source range: 557*0a6a1f1dSLionel Sambuc 558*0a6a1f1dSLionel SambucSource Range 559*0a6a1f1dSLionel Sambuc^^^^^^^^^^^^ 560*0a6a1f1dSLionel Sambuc 561*0a6a1f1dSLionel Sambuc``[deltaLineStart : LEB128, columnStart : LEB128, numLines : LEB128, columnEnd : LEB128]`` 562*0a6a1f1dSLionel Sambuc 563*0a6a1f1dSLionel SambucThe source range record contains the following fields: 564*0a6a1f1dSLionel Sambuc 565*0a6a1f1dSLionel Sambuc* *deltaLineStart*: The difference between the starting line of the 566*0a6a1f1dSLionel Sambuc current mapping region and the starting line of the previous mapping region. 567*0a6a1f1dSLionel Sambuc 568*0a6a1f1dSLionel Sambuc If the current mapping region is the first region in the current 569*0a6a1f1dSLionel Sambuc sub-array, then it stores the starting line of that region. 570*0a6a1f1dSLionel Sambuc 571*0a6a1f1dSLionel Sambuc* *columnStart*: The starting column of the mapping region. 572*0a6a1f1dSLionel Sambuc 573*0a6a1f1dSLionel Sambuc* *numLines*: The difference between the ending line and the starting line 574*0a6a1f1dSLionel Sambuc of the current mapping region. 575*0a6a1f1dSLionel Sambuc 576*0a6a1f1dSLionel Sambuc* *columnEnd*: The ending column of the mapping region. 577