bpfcov

2022-01-10T00:00:00+00:00

This project provides 2 main components:</p>

libBPFCov.so</code> - an out-of-tree LLVM pass</strong> to instrument</strong> your eBPF programs</strong> for coverage.</li>

bpfcov</code> - a CLI</strong> to collect source-based coverage</strong> from your eBPF programs.</li>
</ol>
</th> </th> </th></tr></thead>

</a></td> </a></td> </a></td></tr>
</a></td> </a></td> </a></td></tr>
</a></td> </a></td> </a></td></tr>
</tbody></table>
Overview§</a>
</h2>
This section aims to provide a high-level overiew of the steps you need to get started with bpfcov</strong>.</p>

Compile the LLVM pass</a> obtaining libBPFCov.so</code></li>
Instrument your eBPF program by compiling it and by running the LLVM pass (libBPFCov.so</code>) on it</li>
Build the userspace code of your eBPF application</li>
Execute your eBPF application in the kernel through the bpfcov run ...</code> command</li>
Generate the .profraw</code> file from the run through the bpfcov gen ...</code> command

Having a .profraw</code> makes this tool fully interoperable</li>
Having a .profraw</code> allows you to generate a variety of coverage reports in different formats</li>
</ol>
</li>
Use the LLVM toolchain to create coverage reports as documented in the LLVM docs</a></li>
</ol>
In case you are impatient and want to jump straight into getting your hands dirty, then the examples</a> directory contains a few dummy eBPF programs to showcase what bpfcov</strong> does.</p>
It basically automates steps 2 and 3. Its README</a> contains more details.</p>
While the README of the cli directory</a> gives you more details about the steps 4 and 5 (and also 6).</p>
Usage§</a>
</h2>
Here I will highlight the manual</em> steps to use it.</p>
I suggest you to automate most of them like I did in the examples Makefile</a>.</p>
Anyway, assuming you have built</a> the LLVM pass, you can then use your fresh libBPFCov.so</code> to instrument your eBPF programs for coverage (steps 2 and 3 above).</p>
How to do it?</p>
First, you need to compile your eBPF program almost as usual but to LLVM IR...</p>
clang</span> -g -O2</span> \</span></span>
    -target</span> bpf</span> -D__TARGET_ARCH_x86 -I$(</span>YOUR_INCLUDES</span>)</span> \</span></span>
    -fprofile-instr-generate -fcoverage-mapping</span> \</span></span>
    -emit-llvm -S</span> \</span></span>
    -c</span> program.bpf.c</span> \</span></span>
    -o</span> program.bpf.ll</span></span></code></pre>
Notice it doesn't matter if you use the textual (*.ll</code>) or the binary form (*.bc</code>).
Obviously, the former is more readable.</p>
The same logic applies to opt</code>: by default it generates *.bc</code>.
Using the -S</code> flag you can obtain the output in textual form (*.ll</code>).</p>
Anyhow, it's time to run the LLVM pass on the LLVM IR we obtained.</p>
Let's do it:</p>
opt</span> -load-pass-plugin</span> $(</span>BUILD_DIR</span>)</span>/lib/libBPFCov.so</span> -passes=</span>"bpf-cov"</span> \</span></span>
    -S</span> program.bpf.ll</span> \</span></span>
    -o</span> program.bpf.cov.ll</span></span></code></pre>
We should have obtained a new LLVM IR that's now valid and loadable from the BPF VM in the Linux kernel. Almost there, YaY!</p>
From it, we can obtain a valid BPF ELF now:</p>
llc</span> -march=bpf -filetype=obj -o</span> cov/program.bpf.o program.bpf.cov.ll</span></span></code></pre>
While we are at it, it is also worth running the LLVM pass again (with a flag) to obtain another BPF ELF containing all the profiling</strong> and coverage mapping</strong> info.
It will come in handy later with llvm-cov</code>.</p>
opt</span> -load</span> $(</span>BUILD_DIR</span>)</span>/lib/libBPFCov.so</span> -strip-initializers-only -bpf-cov</span> \</span></span>
    program.bpf.ll</span> |</span> \</span></span>
    llc</span> -march=bpf -filetype=obj -o</span> cov/program.bpf.obj</span></span></code></pre>
At this point, we can compile our userspace application loading the eBPF instrumented program (cov/program.bpf.o</code>).</p>
Doing this when using libbpf</code> and skeletons is very easy. Nothing different from the common steps: bpftool</code>, cc</code>, etc.</p>
In the examples</a> directory, you can find further explainations.</p>
So assuming we got our instrumented binary ready (cov/program</code>), we can run it via the bpfcov</code> CLI.</p>
sudo</span> ./bpfcov run cov/program</span></span>
# Wait for it to exit, or stop it with CTRL+C</span></span>
sudo</span> ./bpfcov gen</span> --unpin</span> cov/program</span></span></code></pre>
Again, in case you wanna know more about these 2 steps, refer this time to the CLI README</a>.</p>
Now we have a magic cov/program.profraw</code> file...</p>
And we can use the LLVM toolchain to generate very fine-grained coverage reports like those in the screenshots!</p>
Refer to the LLVM docs</a> to learn how to do it.</p>
But no worries, it's just about invoking llvm-profdata</code> and llvm-cov</code>:</p>
lvm-profdata</span> merge</span> -sparse</span> cov/program.profraw</span> -o</span> cov/program.profdata</span></span>
llvm-cov</span> show</span> \</span></span>
    --format=html</span> \</span></span>
    --show-line-counts-or-regions --show-region-summary --show-branch-summary</span> \</span></span>
    --instr-profile=cov/profdata.profdata</span> \</span></span>
    -object</span> cov/program.bpf.obj</span> \</span></span>
    --output-dir=cov/html_report</span></span></code></pre>
Anyayws, bpfcov</strong> also provides you an opinionated shortcut command to generate HTML, JSON, and LCOV coverage reports:</p>
./bpfcov</span> out</span> --format=html</span> cov/program.profraw</span></span></code></pre>Development Environment§</a>
</h2>
In order to build</strong> the BPFCov library (libBPFCov.so</code>) you will need:</p>

LLVM 12+</li>
CMake 3.13.4+</li>
C++ compiler that supports C++14</li>
</ul>
In order to use</strong> it, you will need:</p>

clang 12 (to generate the input LLVM files)</li>
its opt</a> binary to run the LLVM pass</li>
</ul>
This project has been tested on 5.15 Linux kernels.</p>
Building§</a>
</h2>
Build as follows:</p>
mkdir</span> -p</span> build</span> &&</span> cd</span> build</span></span>
cmake</span> -DLT_LLVM_INSTALL_DIR=/path/to/llvm/installation</span> ..</span></span>
make</span></span></code></pre>
Notice that the LT_LLVM_INSTALL_DIR</code> variable should be set to the root of either the installation (usually /usr</code>) or the build directory of LLVM.</p>
It is used to locate the corresponding LLVMConfig.cmake</code> script that is used to set the include and the
library paths.</p>
Testing§</a>
</h2>
TBD</strong></p>
To run the tests you will need to install llvm-lit</strong>.</p>
Usually, you can install it with pip</strong>:</p>
pip</span> install lit</span></span></code></pre>
Running the tests is as simple as:</p>
lit</span> build/test</span></span></code></pre>

`Testing§</a> </h2> TBD</strong></p> To run the tests you will need to install llvm-lit</strong>.</p> Usually, you can install it with pip</strong>:</p> pip</span> install lit</span></span></code></pre> Running the tests is as simple as:</p> lit</span> build/test</span></span></code></pre>`

leodido.dev - IR

bpfcov

</th>	</th>	</th></tr></thead>
</a></td>	</a></td>	</a></td></tr>
</a></td>	</a></td>	</a></td></tr>
</a></td>	</a></td>	</a></td></tr> </tbody></table> Overview §</a> </h2> This section aims to provide a high-level overiew of the steps you need to get started with bpfcov</strong>.</p> Compile the LLVM pass</a> obtaining `libBPFCov.so</code></li>` `Instrument your eBPF program by compiling it and by running the LLVM pass (libBPFCov.so</code>) on it</li>` `Build the userspace code of your eBPF application</li>` `Execute your eBPF application in the kernel through the bpfcov run ...</code> command</li>` `Generate the .profraw</code> file from the run through the bpfcov gen ...</code> command`Having a .profraw</code> makes this tool fully interoperable</li> Having a .profraw</code> allows you to generate a variety of coverage reports in different formats</li> </ol> </li> Use the LLVM toolchain to create coverage reports as documented in the LLVM docs</a></li> </ol> In case you are impatient and want to jump straight into getting your hands dirty, then the examples</a> directory contains a few dummy eBPF programs to showcase what bpfcov</strong> does.</p> It basically automates steps 2 and 3. Its README</a> contains more details.</p> While the README of the cli directory</a> gives you more details about the steps 4 and 5 (and also 6).</p> Usage§</a> </h2> Here I will highlight the manual</em> steps to use it.</p> I suggest you to automate most of them like I did in the examples Makefile</a>.</p> Anyway, assuming you have built</a> the LLVM pass, you can then use your fresh libBPFCov.so</code> to instrument your eBPF programs for coverage (steps 2 and 3 above).</p> How to do it?</p> First, you need to compile your eBPF program almost as usual but to LLVM IR...</p> clang</span> -g -O2</span> \</span></span> -target</span> bpf</span> -D__TARGET_ARCH_x86 -I$(</span>YOUR_INCLUDES</span>)</span> \</span></span> -fprofile-instr-generate -fcoverage-mapping</span> \</span></span> -emit-llvm -S</span> \</span></span> -c</span> program.bpf.c</span> \</span></span> -o</span> program.bpf.ll</span></span></code></pre> Notice it doesn't matter if you use the textual (.ll</code>) or the binary form (.bc</code>). Obviously, the former is more readable.</p> The same logic applies to opt</code>: by default it generates .bc</code>. Using the -S</code> flag you can obtain the output in textual form (.ll</code>).</p> Anyhow, it's time to run the LLVM pass on the LLVM IR we obtained.</p> Let's do it:</p> opt</span> -load-pass-plugin</span> $(</span>BUILD_DIR</span>)</span>/lib/libBPFCov.so</span> -passes=</span>"bpf-cov"</span> \</span></span> -S</span> program.bpf.ll</span> \</span></span> -o</span> program.bpf.cov.ll</span></span></code></pre> We should have obtained a new LLVM IR that's now valid and loadable from the BPF VM in the Linux kernel. Almost there, YaY!</p> From it, we can obtain a valid BPF ELF now:</p> llc</span> -march=bpf -filetype=obj -o</span> cov/program.bpf.o program.bpf.cov.ll</span></span></code></pre> While we are at it, it is also worth running the LLVM pass again (with a flag) to obtain another BPF ELF containing all the profiling</strong> and coverage mapping</strong> info. It will come in handy later with llvm-cov</code>.</p> opt</span> -load</span> $(</span>BUILD_DIR</span>)</span>/lib/libBPFCov.so</span> -strip-initializers-only -bpf-cov</span> \</span></span> program.bpf.ll</span> \|</span> \</span></span> llc</span> -march=bpf -filetype=obj -o</span> cov/program.bpf.obj</span></span></code></pre> At this point, we can compile our userspace application loading the eBPF instrumented program (cov/program.bpf.o</code>).</p> Doing this when using libbpf</code> and skeletons is very easy. Nothing different from the common steps: bpftool</code>, cc</code>, etc.</p> In the examples</a> directory, you can find further explainations.</p> So assuming we got our instrumented binary ready (cov/program</code>), we can run it via the bpfcov</code> CLI.</p> sudo</span> ./bpfcov run cov/program</span></span> # Wait for it to exit, or stop it with CTRL+C</span></span> sudo</span> ./bpfcov gen</span> --unpin</span> cov/program</span></span></code></pre> Again, in case you wanna know more about these 2 steps, refer this time to the CLI README</a>.</p> Now we have a magic cov/program.profraw</code> file...</p> And we can use the LLVM toolchain to generate very fine-grained coverage reports like those in the screenshots!</p> Refer to the LLVM docs</a> to learn how to do it.</p> But no worries, it's just about invoking llvm-profdata</code> and llvm-cov</code>:</p> lvm-profdata</span> merge</span> -sparse</span> cov/program.profraw</span> -o</span> cov/program.profdata</span></span> llvm-cov</span> show</span> \</span></span> --format=html</span> \</span></span> --show-line-counts-or-regions --show-region-summary --show-branch-summary</span> \</span></span> --instr-profile=cov/profdata.profdata</span> \</span></span> -object</span> cov/program.bpf.obj</span> \</span></span> --output-dir=cov/html_report</span></span></code></pre> Anyayws, bpfcov</strong> also provides you an opinionated shortcut command to generate HTML, JSON, and LCOV coverage reports:</p> ./bpfcov</span> out</span> --format=html</span> cov/program.profraw</span></span></code></pre>Development Environment§</a> </h2> In order to build</strong> the BPFCov library (libBPFCov.so</code>) you will need:</p> LLVM 12+</li> CMake 3.13.4+</li> C++ compiler that supports C++14</li> </ul> In order to use</strong> it, you will need:</p> clang 12 (to generate the input LLVM files)</li> its opt</a> binary to run the LLVM pass</li> </ul> This project has been tested on 5.15 Linux kernels.</p> Building§</a> </h2> Build as follows:</p> mkdir</span> -p</span> build</span> &&</span> cd</span> build</span></span> cmake</span> -DLT_LLVM_INSTALL_DIR=/path/to/llvm/installation</span> ..</span></span> make</span></span></code></pre> Notice that the LT_LLVM_INSTALL_DIR</code> variable should be set to the root of either the installation (usually /usr</code>) or the build directory of LLVM.</p> It is used to locate the corresponding LLVMConfig.cmake</code> script that is used to set the include and the library paths.</p> Testing§</a> </h2> TBD</strong></p> To run the tests you will need to install llvm-lit</strong>.</p> Usually, you can install it with pip</strong>:</p> pip</span> install lit</span></span></code></pre> Running the tests is as simple as:</p> lit</span> build/test</span></span></code></pre>

leodido.dev - IR

bpfcov

Development Environment§</a> </h2> In order to build</strong> the BPFCov library (libBPFCov.so</code>) you will need:</p> LLVM 12+</li> CMake 3.13.4+</li> C++ compiler that supports C++14</li> </ul> In order to use</strong> it, you will need:</p>

Testing§</a> </h2> TBD</strong></p> To run the tests you will need to install llvm-lit</strong>.</p> Usually, you can install it with pip</strong>:</p> pip</span> install lit</span></span></code></pre> Running the tests is as simple as:</p> lit</span> build/test</span></span></code></pre>

`Testing§</a> </h2> TBD</strong></p> To run the tests you will need to install llvm-lit</strong>.</p> Usually, you can install it with pip</strong>:</p> pip</span> install lit</span></span></code></pre> Running the tests is as simple as:</p> lit</span> build/test</span></span></code></pre>`