---------------------------------------------------------------
- README file for the GCOV extention (LCOV)
- Includes access of Kernel/HYPERVISOR/Userspace Program
---------------------------------------------------------------


Description
-----------

  LCOV is an extension of GCOV, a GNU tool which provides information about
  what parts of a program are actually executed (i.e. "covered") while running
  a particular test case. The functionality is HTML based output. Where coverage 
  rates are additionaly indicated using bar graphs and specific colors.

Contents
---------
1. About lcov config file (/etc/lcovrc)
2. An example of how to access kernel coverage data 
3. An example of how to access HYPERVISOR coverage data
4. An example of how to access coverage data for a user space program


1. About lcov config file (/etc/lcovrc)
----------------------------------------

 The LCOV package is available as either RPM or tarball from:
     
    http://ltp.sourceforge.net/coverage/lcov.php

 LCOV has been modified to support both kernel and xen hypervisor by editing lcov config file.
 LCOV config file will be located in /etc/lcovrc, there is variable called lcov_gcov_dir which
 has the directory path containing gcov kernel files. 

	* Kernel directory path lcov_gcov_dir = /proc/gcov
	* Xen hypervisor directory path lcov_gcov_dir = /proc/xen/gcov

 By defualt config file has kernel directory path (i.e /proc/gcov). User has to specify either 
 kernel path or xen hypervisor path. 	

2. An example of how to access kernel coverage data
----------------------------------------------------
Requirements: get and install gcov-kernel package

 User has to make sure that lcov_gcov_dir should hold the directory path "/proc/gcov" in LCOV 
 config file (i.e /etc/lcovrc).

  a) Capturing the current coverage state to a file

     lcov --capture --output-file kernel.info

  b) Resetting counters

     lcov --zerocounters

  c) Getting HTML output

     genhtml kernel.info

Point the web browser of your choice to the resulting index.html file.

3. An example of how to access HYPERVISOR coverage data
----------------------------------------------------
Requirements: get and install GCOV-HYPERVISOR package

 User has to make sure that lcov_gcov_dir should hold the directory path "/proc/xen/gcov" in LCOV 
 config file (i.e /etc/lcovrc). 

  a) Capturing the current coverage state to a file

     lcov --capture --output-file kernel.info

  b) Resetting counters

     lcov --zerocounters

  c) Getting HTML output

     genhtml kernel.info

Point the web browser of your choice to the resulting index.html file.

4. An example of how to access coverage data for a user space program
---------------------------------------------------------------------
Requirements: compile the program in question using GCC with the options
-fprofile-arcs and -ftest-coverage. Assuming the compile directory is called
"appdir", do the following:

  a) Resetting counters

     lcov --directory appdir --zerocounters

  b) Capturing the current coverage state to a file (works only after the
     application has been started and stopped at least once)

     lcov --directory appdir --capture --output-file app.info

  c) Getting HTML output

     genhtml app.info

Point the web browser of your choice to the resulting index.html file.