Xen devel - May 2013 - [PATCH 2/2] gcov: update documentation on coverage.

From: Frediano Ziglio <frediano.ziglio@citrix.com>

Fix some spelling.
Add documentation for new xencov_split utility.

Signed-off-by: Frediano Ziglio <frediano.ziglio@citrix.com>
---
 docs/misc/coverage.markdown |   67 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 59 insertions(+), 8 deletions(-)

diff --git a/docs/misc/coverage.markdown b/docs/misc/coverage.markdown
index 74af665..b701d7f 100644
--- a/docs/misc/coverage.markdown
+++ b/docs/misc/coverage.markdown
@@ -3,21 +3,22 @@
 Coverare support allow you to get coverage information from Xen execution.
 You can see how many times a line is executed.
 
-The compiler have specific options that enable the collection of these
-information. Every basic block in the code will be instructed by the compiler
-to compute these statistics. It should not be used in production as it slow
+Some compilers have specific options that enable the collection of this
+information. Every basic block in the code will be instrumented by the compiler
+to compute these statistics. It should not be used in production as it slows
 down your hypervisor.
 
 ## Enable coverage
 
-Test coverage support can be turned on compiling Xen with coverage option set
-to y.
+Test coverage support can be turned on compiling Xen with the `coverage` option
set
+to `y`.
 
 Something like:
+
     cd xen
     make coverage=y
 
-(or change your `Config.mk` file).
+(or change your `.config` file).
 
 ## Extract coverage data
 
@@ -28,12 +29,62 @@ so the way you can use coverage from Xen is extract coverage
data from Xen and
 then split these information into files.
 
 To extract data you use a simple utility called `xencov`. Mainly `xencore`
-allow you to do 3 operations:
+allows you to do 3 operations:
 
 * `xencov read` extract data
 * `xencov reset` reset all coverage counters
 * `xencov read-reset` extract data and reset counters at the same time.
 
-Another utility (**TODO**) is used to split extracted data file into files
+Another utility (`xencov_split`) is used to split extracted data file into
files
 needed by userspace tools.
 
+## Split coverage data
+
+Once you extracted data from Xen, it is time to create files which the coverage
tools
+can understand. To do it you need to run `xencov_split` utility.
+
+The utility just takes an input file and splits the blob into gcc .gcda files
+in the same directory that you execute the script. As file names are generated
+relative to the current directory, it could be a good idea to run the script
+from `/` on your build machine.
+
+Code for splitting the blob is put in another utility for some reason:
+* It is simpler to maintain a high level script than a C program;
+* You don''t need to execute on the Xen host so you just need to copy
the file to
+  your development box (you usually need development files anyway).
+
+## Possible use
+
+**This section is just an example on how to use these tools!**
+
+This example assumes you compiled Xen from `~/xen-unstable` and installed into
+the host. **Consider that if you even recompile Xen you are not able to use
+blob extracted from xencov!**
+
+* Ensure the `lcov` package is installed
+* From the Xen host machine extract the coverage blob
+
+        cd /root
+        xencov read coverage.dat
+
+* Copy the extracted blob to your dev machine
+
+        cd ~
+        scp root@myhost:coverage.dat
+
+* Extract the coverage information
+
+        (cd / && xencov_split ~/coverage.dat)
+
+* Produce coverage html output
+
+        cd ~/xen-unstable
+        rm -rf cov.info cov
+        geninfo -o cov.info xen
+        mkdir cov
+        genhtml -o cov cov.info
+
+* See output in a browser
+
+        firefox cov/index.html
+
-- 
1.7.9.5

On Thu, 2013-05-23 at 14:55 +0100, Frediano Ziglio
wrote:
> From: Frediano Ziglio <frediano.ziglio@citrix.com>
> 
> Fix some spelling.
> Add documentation for new xencov_split utility.
> 
> Signed-off-by: Frediano Ziglio <frediano.ziglio@citrix.com>
Acked + applied this and the first one.

For future reference we generally prefer the docs update associated with
a change to be in the same patch.

Also if you could arrange for your series to be threaded together as
replies it makes it much easier for me to track down the various patches
in the series. git send-email will do this for you.
> ---
>  docs/misc/coverage.markdown |   67
+++++++++++++++++++++++++++++++++++++------
>  1 file changed, 59 insertions(+), 8 deletions(-)
> 
> diff --git a/docs/misc/coverage.markdown b/docs/misc/coverage.markdown
> index 74af665..b701d7f 100644
> --- a/docs/misc/coverage.markdown
> +++ b/docs/misc/coverage.markdown
> @@ -3,21 +3,22 @@
>  Coverare support allow you to get coverage information from Xen execution.
>  You can see how many times a line is executed.
>  
> -The compiler have specific options that enable the collection of these
> -information. Every basic block in the code will be instructed by the
compiler
> -to compute these statistics. It should not be used in production as it
slow
> +Some compilers have specific options that enable the collection of this
> +information. Every basic block in the code will be instrumented by the
compiler
> +to compute these statistics. It should not be used in production as it
slows
>  down your hypervisor.
>  
>  ## Enable coverage
>  
> -Test coverage support can be turned on compiling Xen with coverage option
set
> -to y.
> +Test coverage support can be turned on compiling Xen with the `coverage`
option set
> +to `y`.
>  
>  Something like:
> +
>      cd xen
>      make coverage=y
>  
> -(or change your `Config.mk` file).
> +(or change your `.config` file).
>  
>  ## Extract coverage data
>  
> @@ -28,12 +29,62 @@ so the way you can use coverage from Xen is extract
coverage data from Xen and
>  then split these information into files.
>  
>  To extract data you use a simple utility called `xencov`. Mainly `xencore`
> -allow you to do 3 operations:
> +allows you to do 3 operations:
>  
>  * `xencov read` extract data
>  * `xencov reset` reset all coverage counters
>  * `xencov read-reset` extract data and reset counters at the same time.
>  
> -Another utility (**TODO**) is used to split extracted data file into files
> +Another utility (`xencov_split`) is used to split extracted data file into
files
>  needed by userspace tools.
>  
> +## Split coverage data
> +
> +Once you extracted data from Xen, it is time to create files which the
coverage tools
> +can understand. To do it you need to run `xencov_split` utility.
> +
> +The utility just takes an input file and splits the blob into gcc .gcda
files
> +in the same directory that you execute the script. As file names are
generated
> +relative to the current directory, it could be a good idea to run the
script
> +from `/` on your build machine.
> +
> +Code for splitting the blob is put in another utility for some reason:
> +* It is simpler to maintain a high level script than a C program;
> +* You don''t need to execute on the Xen host so you just need to
copy the file to
> +  your development box (you usually need development files anyway).
> +
> +## Possible use
> +
> +**This section is just an example on how to use these tools!**
> +
> +This example assumes you compiled Xen from `~/xen-unstable` and installed
into
> +the host. **Consider that if you even recompile Xen you are not able to
use
> +blob extracted from xencov!**
> +
> +* Ensure the `lcov` package is installed
> +* From the Xen host machine extract the coverage blob
> +
> +        cd /root
> +        xencov read coverage.dat
> +
> +* Copy the extracted blob to your dev machine
> +
> +        cd ~
> +        scp root@myhost:coverage.dat
> +
> +* Extract the coverage information
> +
> +        (cd / && xencov_split ~/coverage.dat)
> +
> +* Produce coverage html output
> +
> +        cd ~/xen-unstable
> +        rm -rf cov.info cov
> +        geninfo -o cov.info xen
> +        mkdir cov
> +        genhtml -o cov cov.info
> +
> +* See output in a browser
> +
> +        firefox cov/index.html
> +