From fc6ff07fd7063ed2a3903b9b2e5e5114b7303e0b Mon Sep 17 00:00:00 2001
From: Wei Liu <liuwe@microsoft.com>
Date: Tue, 17 Oct 2023 23:48:09 +0000
Subject: [PATCH] docs: add a document for collecting coverage data

Signed-off-by: Wei Liu <liuwe@microsoft.com>
---
 docs/coverage.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/coverage.md

diff --git a/docs/coverage.md b/docs/coverage.md
new file mode 100644
index 000000000..f95181c86
--- /dev/null
+++ b/docs/coverage.md
@@ -0,0 +1,55 @@
+# Code coverage
+
+LLVM provides a set of tools to collect code coverage data and present the data
+in human-consumable forms.
+
+## Building a suitable binary
+
+The compiler flag to generate code coverage data has been stabilized since Rust
+1.60.
+
+An instrumented binary can be built with the following command:
+
+```shell
+cargo clean && RUSTFLAGS='-C instrument-coverage' cargo build
+```
+
+Using either `debug` or `release` profile is fine. You will need to adjust
+the path for some commands.
+
+## Running the binary
+
+Run the binary as you normally would. When the process exits, you will see
+files with the prefix `profraw`.
+
+Multiple runs of the same binary will produce multiple `profraw` files.
+
+The more diverse the runs are, the better. Try to exercise different features
+as much as possible.
+
+## Combining raw data
+
+Raw data files can be combined with `llvm-profdata`.
+
+```shell
+rustup component add llvm-tools-preview
+# Assuming profraw files reside in the current directory and its children directories
+find . -name '*.profraw' -exec llvm-profdata merge -sparse {} -o coverage.profdata \;
+```
+
+A file named `coverage.profdata` will be generated.
+
+## Generating HTML files for human consumption
+
+This can be done either with LLVM or `grcov`.
+
+Here is an example using grcov.
+
+```shell
+cargo install grcov
+# Assuming the profdata file is in the top level directory of the Cloud Hypervisor repository
+grcov . --binary-path ./target/x86_64-unknown-linux-gnu/release -s . -t html --branch --ignore-not-existing -o coverage-html-output/
+```
+
+You can then open the `index.html` file under coverage-html-output to see the
+results.